{"id":19657750,"url":"https://github.com/esss/serialchemy","last_synced_at":"2025-04-28T19:32:28.174Z","repository":{"id":37433411,"uuid":"169441696","full_name":"ESSS/serialchemy","owner":"ESSS","description":"SQLAlchemy model serialization","archived":false,"fork":false,"pushed_at":"2024-04-25T14:31:04.000Z","size":5957,"stargazers_count":37,"open_issues_count":2,"forks_count":2,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-04-25T15:42:22.704Z","etag":null,"topics":["hacktoberfest","sql","sqlalchemy"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ESSS.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2019-02-06T16:57:31.000Z","updated_at":"2024-03-29T06:54:22.000Z","dependencies_parsed_at":"2023-11-27T23:24:04.292Z","dependency_job_id":"d7120cf1-878e-459b-9ddd-a7678395155a","html_url":"https://github.com/ESSS/serialchemy","commit_stats":{"total_commits":90,"total_committers":15,"mean_commits":6.0,"dds":0.7333333333333334,"last_synced_commit":"26f04aed8f84cdd32696b3a04c05ce42b873a6c2"},"previous_names":[],"tags_count":273,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ESSS%2Fserialchemy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ESSS%2Fserialchemy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ESSS%2Fserialchemy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ESSS%2Fserialchemy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ESSS","download_url":"https://codeload.github.com/ESSS/serialchemy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224129266,"owners_count":17260591,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","sql","sqlalchemy"],"created_at":"2024-11-11T15:33:33.798Z","updated_at":"2024-11-11T15:33:34.901Z","avatar_url":"https://github.com/ESSS.png","language":"Python","readme":"======================================================================\nSerialchemy\n======================================================================\n\n\n.. image:: https://img.shields.io/pypi/v/serialchemy.svg\n    :target: https://pypi.python.org/pypi/serialchemy\n\n.. image:: https://img.shields.io/pypi/pyversions/serialchemy.svg\n    :target: https://pypi.org/project/serialchemy\n\n.. image:: https://github.com/ESSS/serialchemy/workflows/build/badge.svg\n    :target: https://github.com/ESSS/serialchemy/actions\n\n.. image:: https://codecov.io/gh/ESSS/serialchemy/branch/master/graph/badge.svg\n    :target: https://codecov.io/gh/ESSS/serialchemy\n\n.. image:: https://img.shields.io/readthedocs/serialchemy.svg\n    :target: https://serialchemy.readthedocs.io/en/latest/\n\n.. image:: https://sonarcloud.io/api/project_badges/measure?project=ESSS_serialchemy\u0026metric=alert_status\n    :target: https://sonarcloud.io/project/overview?id=ESSS_serialchemy\n\n\nSQLAlchemy model serialization.\n===============================\n\nMotivation\n----------\n\n**Serialchemy** was developed as a module of Flask-RESTAlchemy_, a lib to create Restful APIs\nusing Flask and SQLAlchemy. We first tried marshmallow-sqlalchemy_, probably the most\nwell-known lib for SQLAlchemy model serialization, but we faced `issues related to nested\nmodels \u003chttps://github.com/marshmallow-code/marshmallow-sqlalchemy/issues/67\u003e`_. We also think\nthat is possible to build a simpler and more maintainable solution by having SQLAlchemy_ in\nmind from the ground up, as opposed to marshmallow-sqlalchemy_ that had to be\ndesigned and built on top of marshmallow_.\n\n.. _SQLAlchemy: www.sqlalchemy.org\n.. _marshmallow-sqlalchemy: http://marshmallow-sqlalchemy.readthedocs.io\n.. _marshmallow: https://marshmallow.readthedocs.io\n.. _Flask-RESTAlchemy: https://github.com/ESSS/flask-restalchemy\n\nHow to Use it\n-------------\n\nSerializing Generic Types\n.........................\n\nSuppose we have an `Employee` SQLAlchemy_ model declared:\n\n.. code-block:: python\n\n    class Employee(Base):\n        __tablename__ = \"Employee\"\n\n        id = Column(Integer, primary_key=True)\n        fullname = Column(String)\n        admission = Column(DateTime, default=datetime(2000, 1, 1))\n        company_id = Column(ForeignKey(\"Company.id\"))\n        company = relationship(Company)\n        company_name = column_property(\n            select([Company.name]).where(Company.id == company_id)\n        )\n        password = Column(String)\n\n`Generic Types`_ are automatically serialized by `ModelSerializer`:\n\n.. code-block:: python\n\n    from serialchemy import ModelSerializer\n\n    emp = Employee(fullname=\"Roberto Silva\", admission=datetime(2019, 4, 2))\n\n    serializer = ModelSerializer(Employee)\n    serializer.dump(emp)\n\n    # \u003e\u003e\n    {\n        \"id\": None,\n        \"fullname\": \"Roberto Silva\",\n        \"admission\": \"2019-04-02T00:00:00\",\n        \"company_id\": None,\n        \"company_name\": None,\n        \"password\": None,\n    }\n\nNew items can be deserialized by the same serializer:\n\n.. code-block:: python\n\n    new_employee = {\"fullname\": \"Jobson Gomes\", \"admission\": \"2018-02-03\"}\n    serializer.load(new_employee)\n\n    # \u003e\u003e \u003cEmployee object at 0x000001C119DE3940\u003e\n\nSerializers do not commit into the database. You must do this by yourself:\n\n.. code-block:: python\n\n    emp = serializer.load(new_employee)\n    session.add(emp)\n    session.commit()\n\n.. _`Generic Types`: https://docs.sqlalchemy.org/en/rel_1_2/core/type_basics.html#generic-types\n\nCustom Serializers\n..................\n\nFor anything beyond `Generic Types`_ we must extend the `ModelSerializer` class:\n\n.. code-block:: python\n\n    class EmployeeSerializer(ModelSerializer):\n\n        password = Field(load_only=True)  # passwords should be only deserialized\n        company = NestedModelField(Company)  # dump company as nested object\n\n\n    serializer = EmployeeSerializer(Employee)\n    serializer.dump(emp)\n    # \u003e\u003e\n    {\n        \"id\": 1,\n        \"fullname\": \"Roberto Silva\",\n        \"admission\": \"2019-04-02T00:00:00\",\n        \"company\": {\"id\": 3, \"name\": \"Acme Co\"},\n    }\n\n\nExtend Polymorphic Serializer\n+++++++++++++++++++++++++++++\nOne of the possibilities is to serialize SQLalchemy joined table inheritance and\nit child tables as well. To do such it's necessary to set a variable with\nthe desired model class name. Take this `Employee` class with for instance and let us\nassume it have a joined table inheritance:\n\n.. code-block:: python\n\n    class Employee(Base):\n        ...\n        type = Column(String(50))\n\n        __mapper_args__ = {\"polymorphic_identity\": \"employee\", \"polymorphic_on\": type}\n\n\n    class Engineer(Employee):\n        __tablename__ = \"Engineer\"\n        id = Column(Integer, ForeignKey(\"employee.id\"), primary_key=True)\n        association = relationship(Association)\n\n        __mapper_args__ = {\n            \"polymorphic_identity\": \"engineer\",\n        }\n\nTo use a extended `ModelSerializer` class on the `Engineer` class, you should create\nthe serializer as it follows:\n\n.. code-block:: python\n\n    class EmployeeSerializer(\n        PolymorphicModelSerializer\n    ):  # Since this class will be polymorphic\n\n        password = Field(load_only=True)\n        company = NestedModelField(Company)\n\n\n    class EngineerSerializer(EmployeeSerializer):\n        __model_class__ = Engineer  # This is the table Serialchemy will refer to\n        association = NestedModelField(Association)\n\nContributing\n------------\n\nFor guidance on setting up a development environment and how to make a\ncontribution to serialchemy, see the `contributing guidelines`_.\n\n.. _contributing guidelines: https://github.com/ESSS/serialchemy/blob/master/CONTRIBUTING.rst\n\n\nRelease\n-------\nA reminder for the maintainers on how to make a new release.\n\nNote that the VERSION should folow the semantic versioning as X.Y.Z\nEx.: v1.0.5\n\n1. Create a ``release-VERSION`` branch from ``upstream/master``.\n2. Update ``CHANGELOG.rst``.\n3. Push a branch with the changes.\n4. Once all builds pass, push a ``VERSION`` tag to ``upstream``.\n5. Merge the PR.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesss%2Fserialchemy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fesss%2Fserialchemy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesss%2Fserialchemy/lists"}