# Welcome to ORMatic
ORMatic is a python package that automatically converts python dataclasses to sqlalchemy tables.
This is done using the [declarative mapping](https://docs.sqlalchemy.org/en/20/orm/mapping_styles.html#declarative-mapping).
The package outputs a file that can be used as an [SQLAlchemy](https://www.sqlalchemy.org/) interface.
When designing the dataclasses that should be mapped there are a couple of rules that need to be followed:
- Fields that are not mapped start with an `_` (underscore).
- The only allowed union is the `Optional[_T]` union. Whenever you want a union of other types, use common
superclasses as type instead.
- Iterables are never optional and never nested.
If you want an optional iterable, use an empty iterable as default factory instead.
- Superclasses that are not the first mentioned superclass are not queryable via abstract queries. (Polymorphic identity)
If your dataclasses are not compatible with this pattern, there are two workarounds,
the Alternative Mapping and the Type Decorator.
## Features:
- Automatic conversion of dataclasses to sqlalchemy tables.
- Automatic application of relationships.
- Automatic generation of ORM interface.
- ORM interface never affects your existing code.
- Support for inheritance.
- Support for optional fields.
- Support for nested dataclasses.
- Support for many-many relationships.
- Support for self-referencing relationships.
## Example
The most common use case is to create an ORM for an existing set of dataclasses.
An example for such a set of dataclasses is found in
[example.py](https://github.com/tomsch420/ormatic/blob/master/test/classes/example_classes.py).
The automatically generated ORM interface is found in [sqlalchemy_interface.py](https://github.com/tomsch420/ormatic/blob/master/test/classes/sqlalchemy_interface.py).
Example usage of the ORM interface is found in [integration.py](https://github.com/tomsch420/ormatic/blob/master/test/integration.py).
The following script generates the bindings in [sqlalchemy_interface.py](https://github.com/tomsch420/ormatic/blob/master/test/classes/sqlalchemy_interface.py).
```python
from enum import Enum
import test.classes.example_classes
from ormatic.ormatic import ORMatic
from ormatic.dao import AlternativeMapping
from ormatic.utils import recursive_subclasses, classes_of_module
from dataclasses import is_dataclass
def main():
# get classes that should be mapped
classes = set(recursive_subclasses(AlternativeMapping))
classes |= set(classes_of_module(test.classes.example_classes))
# remove classes that should not be mapped
classes -= set(recursive_subclasses(Enum))
classes -= set([cls for cls in classes if not is_dataclass(cls)])
ormatic = ORMatic(classes)
ormatic.make_all_tables()
with open('orm_interface.py', 'w') as f:
ormatic.to_sqlalchemy_file(f)
if __name__ == '__main__':
main()
```
# TODO List
- ~~Nothing~~
Raw data
{
"_id": null,
"home_page": null,
"name": "ormatic",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ORM, sqlalchemy, dataclasses, database, models, automatic",
"author": null,
"author_email": "Tom Schierenbeck <tom_sch@uni-bremen.de>",
"download_url": "https://files.pythonhosted.org/packages/70/b9/1f1a10e87d15064466be6fa03ddfd9750b8abef09938ff52f143509f7eb2/ormatic-1.1.10.tar.gz",
"platform": null,
"description": "# Welcome to ORMatic\n\nORMatic is a python package that automatically converts python dataclasses to sqlalchemy tables.\nThis is done using the [declarative mapping](https://docs.sqlalchemy.org/en/20/orm/mapping_styles.html#declarative-mapping).\nThe package outputs a file that can be used as an [SQLAlchemy](https://www.sqlalchemy.org/) interface. \n\nWhen designing the dataclasses that should be mapped there are a couple of rules that need to be followed:\n- Fields that are not mapped start with an `_` (underscore).\n- The only allowed union is the `Optional[_T]` union. Whenever you want a union of other types, use common \nsuperclasses as type instead.\n- Iterables are never optional and never nested. \nIf you want an optional iterable, use an empty iterable as default factory instead.\n- Superclasses that are not the first mentioned superclass are not queryable via abstract queries. (Polymorphic identity) \n\nIf your dataclasses are not compatible with this pattern, there are two workarounds,\nthe Alternative Mapping and the Type Decorator.\n\n## Features:\n\n- Automatic conversion of dataclasses to sqlalchemy tables.\n- Automatic application of relationships.\n- Automatic generation of ORM interface.\n- ORM interface never affects your existing code.\n\n- Support for inheritance.\n- Support for optional fields.\n- Support for nested dataclasses.\n- Support for many-many relationships.\n- Support for self-referencing relationships.\n\n## Example\n\nThe most common use case is to create an ORM for an existing set of dataclasses.\nAn example for such a set of dataclasses is found in \n[example.py](https://github.com/tomsch420/ormatic/blob/master/test/classes/example_classes.py).\nThe automatically generated ORM interface is found in [sqlalchemy_interface.py](https://github.com/tomsch420/ormatic/blob/master/test/classes/sqlalchemy_interface.py).\nExample usage of the ORM interface is found in [integration.py](https://github.com/tomsch420/ormatic/blob/master/test/integration.py).\n\nThe following script generates the bindings in [sqlalchemy_interface.py](https://github.com/tomsch420/ormatic/blob/master/test/classes/sqlalchemy_interface.py).\n```python\nfrom enum import Enum\nimport test.classes.example_classes\nfrom ormatic.ormatic import ORMatic\nfrom ormatic.dao import AlternativeMapping\nfrom ormatic.utils import recursive_subclasses, classes_of_module\nfrom dataclasses import is_dataclass\n\n\ndef main():\n \n # get classes that should be mapped\n classes = set(recursive_subclasses(AlternativeMapping))\n classes |= set(classes_of_module(test.classes.example_classes))\n \n # remove classes that should not be mapped\n classes -= set(recursive_subclasses(Enum))\n classes -= set([cls for cls in classes if not is_dataclass(cls)])\n \n ormatic = ORMatic(classes)\n ormatic.make_all_tables()\n\n with open('orm_interface.py', 'w') as f:\n ormatic.to_sqlalchemy_file(f)\n\n \nif __name__ == '__main__':\n main()\n\n```\n\n# TODO List\n- ~~Nothing~~\n",
"bugtrack_url": null,
"license": null,
"summary": "Automatic Creation of ORM Models from Python Dataclasses.",
"version": "1.1.10",
"project_urls": {
"Bug Tracker": "https://github.com/tomsch420/ormatic/issues",
"Source": "https://github.com/tomsch420/ormatic"
},
"split_keywords": [
"orm",
" sqlalchemy",
" dataclasses",
" database",
" models",
" automatic"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b5d6b31c4dedee3bd7e6b920df717146d367d036fafb5fe0b574801ebc4c08d1",
"md5": "ce4a4c00d2faccf676a9b979a6098bd9",
"sha256": "b396284a8a5a26a3e8d0d60fd439451312c3a42c39f201419f9fc7936e0e4dd4"
},
"downloads": -1,
"filename": "ormatic-1.1.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ce4a4c00d2faccf676a9b979a6098bd9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 17567,
"upload_time": "2025-07-22T07:28:25",
"upload_time_iso_8601": "2025-07-22T07:28:25.133900Z",
"url": "https://files.pythonhosted.org/packages/b5/d6/b31c4dedee3bd7e6b920df717146d367d036fafb5fe0b574801ebc4c08d1/ormatic-1.1.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "70b91f1a10e87d15064466be6fa03ddfd9750b8abef09938ff52f143509f7eb2",
"md5": "b95648db82e6257f828ea7abf9ba1943",
"sha256": "620c49c026daca89cca5561e056d7c25afc8872b84e4c67888b20b8f3b35cfc1"
},
"downloads": -1,
"filename": "ormatic-1.1.10.tar.gz",
"has_sig": false,
"md5_digest": "b95648db82e6257f828ea7abf9ba1943",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 25471,
"upload_time": "2025-07-22T07:28:26",
"upload_time_iso_8601": "2025-07-22T07:28:26.157551Z",
"url": "https://files.pythonhosted.org/packages/70/b9/1f1a10e87d15064466be6fa03ddfd9750b8abef09938ff52f143509f7eb2/ormatic-1.1.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-22 07:28:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tomsch420",
"github_project": "ormatic",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "sqlalchemy",
"specs": []
},
{
"name": "rustworkx",
"specs": []
},
{
"name": "jinja2",
"specs": []
}
],
"lcname": "ormatic"
}
JSON
