Initial commit

.ci/aptPackagesToInstall.txt

@@ -0,0 +1 @@
+python3-ujson

.ci/pythonPackagesToInstallFromGit.txt

@@ -0,0 +1 @@
+https://github.com/KOLANICH/transformerz.py.git

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+indent_style = tab
+indent_size = 4
+insert_final_newline = true
+end_of_line = lf
+
+[*.{yml,yaml}]
+indent_style = space
+indent_size = 2

.github/.templateMarker

@@ -0,0 +1 @@
+KOLANICH/python_project_boilerplate.py

.github/dependabot.yml

@@ -0,0 +1,8 @@
+version: 2
+updates:
+ - package-ecosystem: "pip"
+ directory: "/"
+ schedule:
+ interval: "daily"
+ allow:
+ - dependency-type: "all"

.github/workflows/CI.yml

@@ -0,0 +1,15 @@
+name: CI
+on:
+ push:
+ branches: [master]
+ pull_request:
+ branches: [master]
+
+jobs:
+ build:
+ runs-on: ubuntu-22.04
+ steps:
+ - name: typical python workflow
+ uses: KOLANICH-GHActions/typical-python-workflow@master
+ with:
+ github_token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1,11 @@
+__pycache__
+*.py[co]
+/*.egg-info
+*.srctrlbm
+*.srctrldb
+build
+dist
+.eggs
+monkeytype.sqlite3
+/tests/testSavedDataRootDir
+/.ipynb_checkpoints

.gitlab-ci.yml

@@ -0,0 +1,53 @@
+#image: pypy:latest
+image: registry.gitlab.com/kolanich-subgroups/docker-images/fixed_python:latest
+
+variables:
+ DOCKER_DRIVER: overlay2
+ SAST_ANALYZER_IMAGE_TAG: latest
+ SAST_DISABLE_DIND: "true"
+ SAST_CONFIDENCE_LEVEL: 5
+ CODECLIMATE_VERSION: latest
+
+include:
+ - template: SAST.gitlab-ci.yml
+ - template: Code-Quality.gitlab-ci.yml
+ - template: License-Management.gitlab-ci.yml
+
+build:
+ tags:
+ - shared
+ - linux
+ stage: build
+ variables:
+ GIT_DEPTH: "1"
+ PYTHONUSERBASE: ${CI_PROJECT_DIR}/python_user_packages
+
+ before_script:
+ - export PATH="$PATH:$PYTHONUSERBASE/bin" # don't move into `variables`
+ - apt-get update
+ - apt-get -y install python3-lz4 python3-msgpack python3-brotli python3-cbor python3-ujson
+ - pip3 install --upgrade https://gitlab.com/KOLANICH/py-lmdb/-/jobs/artifacts/gitlab/raw/wheels/lmdb-0.CI_cpython_latest-py3-none-any.whl?job=build
+ - python3 ./fix_python_modules_paths.py
+ - mkdir -p ./tests/databasesFiles
+ - mount -t ramfs ramfs ./tests/databasesFiles
+
+ script:
+ - python3 setup.py bdist_wheel
+ - mv ./dist/*.whl ./dist/Cache-0.CI-py3-none-any.whl
+ - pip3 install --upgrade -e ./[msgpack,lz4,brotli,zopflipy,cbor,zstd,lmdb]
+ - coverage run --source=Cache -m pytest --junitxml=./rspec.xml ./tests/test.py
+ - coverage report -m
+ - coverage xml
+
+ coverage: /^TOTAL(?:\s+\d+){4}\s+(\d+%).+/
+
+ cache:
+ paths:
+ - $PYTHONUSERBASE
+
+ artifacts:
+ paths:
+ - dist
+ reports:
+ junit: ./rspec.xml
+ cobertura: ./coverage.xml

.travis.yml

@@ -0,0 +1,21 @@
+os:
+ - linux
+ - osx
+dist: trusty
+language: python
+python:
+ - 3.4
+ - 3.5
+ - 3.6
+ - 3.7
+ - nightly
+ - pypy3
+ - pypy3-nightly
+before_install:
+ - pip3 install --upgrade setuptools setuptools_scm coveralls
+install:
+ - python setup.py install
+script:
+ - coverage run --source=Cache python tests/test.py test
+after_success:
+ - coveralls

Code_Of_Conduct.md

@@ -0,0 +1 @@
+No codes of conduct!

MANIFEST.in

@@ -0,0 +1,4 @@
+include UNLICENSE
+include *.md
+include tests
+include .editorconfig

ReadMe.md

@@ -0,0 +1,56 @@
+urm.py [![Unlicensed work](https://raw.githubusercontent.com/unlicense/unlicense.org/master/static/favicon.png)](https://unlicense.org/)
+======
+~~[wheel (GitLab)](https://gitlab.com/KOLANICH/urm.py/-/jobs/artifacts/master/raw/dist/urm-0.CI-py3-none-any.whl?job=build)~~
+~~[wheel (GHA via `nightly.link`)](https://nightly.link/KOLANICH-libs/urm.py/workflows/CI/master/urm-0.CI-py3-none-any.whl)~~
+~~![GitLab Build Status](https://gitlab.com/KOLANICH/urm.py/badges/master/pipeline.svg)~~
+~~![GitLab Coverage](https://gitlab.com/KOLANICH/urm.py/badges/master/coverage.svg)~~
+~~[![GitHub Actions](https://github.com/KOLANICH-libs/urm.py/workflows/CI/badge.svg)](https://github.com/KOLANICH-libs/urm.py/actions/)~~
+[![Libraries.io Status](https://img.shields.io/librariesio/github/KOLANICH-libs/urm.py.svg)](https://libraries.io/github/KOLANICH-libs/urm.py)
+[![Code style: antiflash](https://img.shields.io/badge/code%20style-antiflash-FFF.svg)](https://codeberg.org/KOLANICH-tools/antiflash.py)
+
+Unrelational mapper.
+
+Sometimes you need to store some data somewhen and lazily retrieve as class fields and we don't want to write lot of boilerplate code and maintain this piece of shit. Object-relational mappers solve this problem by mapping classes to database tables, objects - to rows, object hierarchy to public and foreign keys.
+
+But sometimes we don't need to store the data in relational databases. We need to store data in entities like files, archives, remote servers using REST/GraphQL API, etc. So we generalize a bit.
+
+This stuff utilizes my other library `transformerz` of composable 2-way transformations.
+
+Tutorial
+--------
+
+It is [strongly](/issue/1) recommended to read the tutorial before using the lib. [`tutorial.ipynb`](./tutorial.ipynb)[![NBViewer](https://nbviewer.org/static/ico/ipynb_icon_16x16.png)](https://nbviewer.org/urls/codeberg.org/KOLANICH-libs/urm.py/raw/branch/master/tutorial.ipynb)
+
+TL;DR. Data model
+-----------------
+
+We tie stored entities not to objects, but properties in classes. Entities are stored in underlying key-value storage.
+
+* When we first time access a property in the class, it is loaded into a cache and then returned.
+* subsequent accesses return the stuff from the cache.
+* we can `save` the stuff from the cache to the storage explicitly.
+* to create a storage from scratch, we put the data into a cache and then `save` it.
+
+Then we heavily abstrage the stuff.
+
+A `key` is a `tuple` of strings and numbers. It is an unique identifier of a piece of data. It is decoupled from the actual storage implementation. We address data by keys.
+
+To define the way we are going to store data we need to answer to the following "orthogonal" questions:
+
+* WHERE are we going to store it? `Saver` object is an answer. `Mapper.saver` answers the question.
+* WHAT is the mapping between our internal `key`s and `key`s in the storage of this piece of data? A `key` is an answer. `Mapper.key` answers this question.
+
+For cold storage we need to answer an additional question:
+
+* HOW are we going to serialize the data? `transformerz.Transformer` object is an answer. `ColdMapper.serializer` answers this question.
+
+So `Mapper` object answers the questions related to storage of values.
+
+To create a bidirectional mapping between class properties, we need to answer the following questions:
+
+* What pattern of access to the data should be optimized for? `FieldStrategy` subclasses are the answers.
+ * `ColdStrategy` optimizes for frequent rather cheap accesses to volatile data.
+ * Requires to know how we STORE the data. `ColdMapper` object is an answer. `FieldStrategy.cold` answers this question.
+ * `CachedStrategy` optimizes for frequent rather expensive accesses to not very volatile data.
+ * *Additionally* requires to know how we CACHE the data? `HotMapper` object is an answer. `FieldStrategy.hot` answers this question.
+ * How do we create our internal `key`s? `Field` subclasses contain the answers.

UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org/>

pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61.2.0", "wheel", "setuptools_scm[toml]>=3.4.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "urm"
+description = "Unrelational mapper. Saves and loads data not only from key-value storages."
+readme = "ReadMe.md"
+authors = [{name = "KOLANICH"}]
+license = {text = "Unlicense"}
+classifiers = [
+ "Development Status :: 4 - Beta",
+ "Environment :: Other Environment",
+ "Intended Audience :: Developers",
+ "License :: Public Domain",
+ "Operating System :: OS Independent",
+ "Programming Language :: Python",
+ "Programming Language :: Python :: 3",
+ "Programming Language :: Python :: 3 :: Only",
+ "Topic :: Software Development :: Libraries :: Python Modules",
+]
+keywords = ["urm"]
+urls = {Homepage = "https://codeberg.org/KOLANICH-libs/urm.py"}
+requires-python = ">=3.4"
+dependencies = [
+ "transformerz", # @ git+https://codeberg.org/KOLANICH-libs/transformerz.py.git
+]
+dynamic = ["version"]
+
+[tool.setuptools]
+packages = ["urm"]
+zip-safe = true
+include-package-data = false
+
+[tool.setuptools_scm]