strawberry-sqlalchemy-mapper


Namestrawberry-sqlalchemy-mapper JSON
Version 0.5.0 PyPI version JSON
download
home_pagehttps://strawberry.rocks/
SummaryA library for autogenerating Strawberry GraphQL types from SQLAlchemy models.
upload_time2024-11-12 13:10:43
maintainerNone
docs_urlNone
authorTim Dumol
requires_python<4.0,>=3.8
licenseMIT
keywords graphql sqlalchemy strawberry
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage
            # strawberry-sqlalchemy-mapper


Strawberry-sqlalchemy-mapper is the simplest way to implement autogenerated strawberry types for columns and relationships in SQLAlchemy models.


- Instead of manually listing every column and relationship in a SQLAlchemy model, strawberry-sqlalchemy-mapper
lets you decorate a class declaration and it will automatically generate the necessary strawberry fields
for all columns and relationships (subject to the limitations below) in the given model.

- Native support for most of SQLAlchemy's most common types.
- Extensible to arbitrary custom SQLAlchemy types.
- Automatic batching of queries, avoiding N+1 queries when getting relationships
- Support for SQLAlchemy >=1.4.x
- Lightweight and fast.

## Getting Started

strawberry-sqlalchemy-mapper is available on [PyPi](https://pypi.org/project/strawberry-sqlalchemy-mapper/)

```
pip install strawberry-sqlalchemy-mapper
```


First, define your sqlalchemy model:

```python
# models.py
from sqlalchemy import Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()


class Employee(Base):
    __tablename__ = "employee"
    id = Column(UUID, primary_key=True)
    name = Column(String, nullable=False)
    password_hash = Column(String, nullable=False)
    department_id = Column(UUID, ForeignKey("department.id"))
    department = relationship("Department", back_populates="employees")


class Department(Base):
    __tablename__ = "department"
    id = Column(UUID, primary_key=True)
    name = Column(String, nullable=False)
    employees = relationship("Employee", back_populates="department")
```

Next, decorate a type with `strawberry_sqlalchemy_mapper.type()`
to register it as a strawberry type for the given SQLAlchemy model.
This will automatically add fields for the model's columns, relationships, association proxies,
and hybrid properties. For example:

```python
# elsewhere
# ...
from strawberry_sqlalchemy_mapper import StrawberrySQLAlchemyMapper

strawberry_sqlalchemy_mapper = StrawberrySQLAlchemyMapper()


@strawberry_sqlalchemy_mapper.type(models.Employee)
class Employee:
    __exclude__ = ["password_hash"]


@strawberry_sqlalchemy_mapper.type(models.Department)
class Department:
    pass


@strawberry.type
class Query:
    @strawberry.field
    def departments(self):
        return db.session.scalars(select(models.Department)).all()


# context is expected to have an instance of StrawberrySQLAlchemyLoader
class CustomGraphQLView(GraphQLView):
    def get_context(self):
        return {
            "sqlalchemy_loader": StrawberrySQLAlchemyLoader(bind=YOUR_SESSION),
        }


# call finalize() before using the schema:
# (note that models that are related to models that are in the schema
# are automatically mapped at this stage -- e.g., Department is mapped
# because employee.department is a relationshp to Department)
strawberry_sqlalchemy_mapper.finalize()
# only needed if you have polymorphic types
additional_types = list(strawberry_sqlalchemy_mapper.mapped_types.values())
schema = strawberry.Schema(
    query=Query,
    mutation=Mutation,
    extensions=extensions,
    types=additional_types,
)

# You can now query, e.g.:
"""
query {
    departments {
        id
        name
        employees {
            edge {
                node {
                    id
                    name
                    department {
                        # Just an example of nested relationships
                        id
                        name
                    }
                }
            }
        }
    }
}
"""
```

## Limitations

SQLAlchemy Models -> Strawberry Types and Interfaces are expected to have a consistent
(customizable) naming convention. These can be configured by passing `model_to_type_name`
and `model_to_interface_name` when constructing the mapper.

Natively supports the following SQLAlchemy types:

```python
Integer: int,
Float: float,
BigInteger: BigInt,
Numeric: Decimal,
DateTime: datetime,
Date: date,
Time: time,
String: str,
Text: str,
Boolean: bool,
Unicode: str,
UnicodeText: str,
SmallInteger: int,
SQLAlchemyUUID: uuid.UUID,
VARCHAR: str,
ARRAY[T]: List[T] # PostgreSQL array
JSON: JSON # SQLAlchemy JSON
Enum: (the Python enum it is mapped to, which should be @strawberry.enum-decorated)
```

Additional types can be supported by passing `extra_sqlalchemy_type_to_strawberry_type_map`,
although support for `TypeDecorator` types is untested.

Association proxies are expected to be of the form `association_proxy('relationship1', 'relationship2')`,
i.e., both properties are expected to be relationships.

Roots of polymorphic hierarchies **are supported**, but are also expected to be registered via
`strawberry_sqlalchemy_mapper.interface()`, and its concrete type and
its descendants are expected to inherit from the interface:

```python
class Book(Model):
    id = Column(UUID, primary_key=True)


class Novel(Book):
    pass


class ShortStory(Book):
    pass


# in another file
strawberry_sqlalchemy_mapper = StrawberrySQLAlchemyMapper()


@strawberry_sqlalchemy_mapper.interface(models.Book)
class BookInterface:
    pass


@strawberry_sqlalchemy_mapper.type(models.Book)
class Book:
    pass


@strawberry_sqlalchemy_mapper.type(models.Novel)
class Novel:
    pass


@strawberry_sqlalchemy_mapper.type(models.ShortStory)
class ShortStory:
    pass
```

## Contributing

We encourage you to contribute to strawberry-sqlalchemy-mapper! Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature)
3. Commit your Changes (git commit -m 'Add some feature')
4. Push to the Branch (git push origin feature)
5. Open a Pull Request


### Prerequisites

This project uses `pre-commit`_, please make sure to install it before making any
changes::

    pip install pre-commit
    cd strawberry-sqlalchemy-mapper
    pre-commit install

It is a good idea to update the hooks to the latest version::

    pre-commit autoupdate

Don't forget to tell your contributors to also install and use pre-commit.

### Installation

```bash
pip install -r requirements.txt
```

Install [PostgreSQL 14+](https://www.postgresql.org/download/)

### Test

```bash
pytest
```

## ⚖️ LICENSE

MIT © [strawberry-sqlalchemy-mapper](LICENSE.txt)

            

Raw data

            {
    "_id": null,
    "home_page": "https://strawberry.rocks/",
    "name": "strawberry-sqlalchemy-mapper",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<4.0,>=3.8",
    "maintainer_email": null,
    "keywords": "graphql, sqlalchemy, strawberry",
    "author": "Tim Dumol",
    "author_email": "tim@timdumol.com",
    "download_url": "https://files.pythonhosted.org/packages/94/5f/2b0631d67cc90100ca372dcf4ed29bbf48306108998c7ad417e35fb8d116/strawberry_sqlalchemy_mapper-0.5.0.tar.gz",
    "platform": null,
    "description": "# strawberry-sqlalchemy-mapper\n\n\nStrawberry-sqlalchemy-mapper is the simplest way to implement autogenerated strawberry types for columns and relationships in SQLAlchemy models.\n\n\n- Instead of manually listing every column and relationship in a SQLAlchemy model, strawberry-sqlalchemy-mapper\nlets you decorate a class declaration and it will automatically generate the necessary strawberry fields\nfor all columns and relationships (subject to the limitations below) in the given model.\n\n- Native support for most of SQLAlchemy's most common types.\n- Extensible to arbitrary custom SQLAlchemy types.\n- Automatic batching of queries, avoiding N+1 queries when getting relationships\n- Support for SQLAlchemy >=1.4.x\n- Lightweight and fast.\n\n## Getting Started\n\nstrawberry-sqlalchemy-mapper is available on [PyPi](https://pypi.org/project/strawberry-sqlalchemy-mapper/)\n\n```\npip install strawberry-sqlalchemy-mapper\n```\n\n\nFirst, define your sqlalchemy model:\n\n```python\n# models.py\nfrom sqlalchemy import Column, Integer, String\nfrom sqlalchemy.ext.declarative import declarative_base\n\nBase = declarative_base()\n\n\nclass Employee(Base):\n    __tablename__ = \"employee\"\n    id = Column(UUID, primary_key=True)\n    name = Column(String, nullable=False)\n    password_hash = Column(String, nullable=False)\n    department_id = Column(UUID, ForeignKey(\"department.id\"))\n    department = relationship(\"Department\", back_populates=\"employees\")\n\n\nclass Department(Base):\n    __tablename__ = \"department\"\n    id = Column(UUID, primary_key=True)\n    name = Column(String, nullable=False)\n    employees = relationship(\"Employee\", back_populates=\"department\")\n```\n\nNext, decorate a type with `strawberry_sqlalchemy_mapper.type()`\nto register it as a strawberry type for the given SQLAlchemy model.\nThis will automatically add fields for the model's columns, relationships, association proxies,\nand hybrid properties. For example:\n\n```python\n# elsewhere\n# ...\nfrom strawberry_sqlalchemy_mapper import StrawberrySQLAlchemyMapper\n\nstrawberry_sqlalchemy_mapper = StrawberrySQLAlchemyMapper()\n\n\n@strawberry_sqlalchemy_mapper.type(models.Employee)\nclass Employee:\n    __exclude__ = [\"password_hash\"]\n\n\n@strawberry_sqlalchemy_mapper.type(models.Department)\nclass Department:\n    pass\n\n\n@strawberry.type\nclass Query:\n    @strawberry.field\n    def departments(self):\n        return db.session.scalars(select(models.Department)).all()\n\n\n# context is expected to have an instance of StrawberrySQLAlchemyLoader\nclass CustomGraphQLView(GraphQLView):\n    def get_context(self):\n        return {\n            \"sqlalchemy_loader\": StrawberrySQLAlchemyLoader(bind=YOUR_SESSION),\n        }\n\n\n# call finalize() before using the schema:\n# (note that models that are related to models that are in the schema\n# are automatically mapped at this stage -- e.g., Department is mapped\n# because employee.department is a relationshp to Department)\nstrawberry_sqlalchemy_mapper.finalize()\n# only needed if you have polymorphic types\nadditional_types = list(strawberry_sqlalchemy_mapper.mapped_types.values())\nschema = strawberry.Schema(\n    query=Query,\n    mutation=Mutation,\n    extensions=extensions,\n    types=additional_types,\n)\n\n# You can now query, e.g.:\n\"\"\"\nquery {\n    departments {\n        id\n        name\n        employees {\n            edge {\n                node {\n                    id\n                    name\n                    department {\n                        # Just an example of nested relationships\n                        id\n                        name\n                    }\n                }\n            }\n        }\n    }\n}\n\"\"\"\n```\n\n## Limitations\n\nSQLAlchemy Models -> Strawberry Types and Interfaces are expected to have a consistent\n(customizable) naming convention. These can be configured by passing `model_to_type_name`\nand `model_to_interface_name` when constructing the mapper.\n\nNatively supports the following SQLAlchemy types:\n\n```python\nInteger: int,\nFloat: float,\nBigInteger: BigInt,\nNumeric: Decimal,\nDateTime: datetime,\nDate: date,\nTime: time,\nString: str,\nText: str,\nBoolean: bool,\nUnicode: str,\nUnicodeText: str,\nSmallInteger: int,\nSQLAlchemyUUID: uuid.UUID,\nVARCHAR: str,\nARRAY[T]: List[T] # PostgreSQL array\nJSON: JSON # SQLAlchemy JSON\nEnum: (the Python enum it is mapped to, which should be @strawberry.enum-decorated)\n```\n\nAdditional types can be supported by passing `extra_sqlalchemy_type_to_strawberry_type_map`,\nalthough support for `TypeDecorator` types is untested.\n\nAssociation proxies are expected to be of the form `association_proxy('relationship1', 'relationship2')`,\ni.e., both properties are expected to be relationships.\n\nRoots of polymorphic hierarchies **are supported**, but are also expected to be registered via\n`strawberry_sqlalchemy_mapper.interface()`, and its concrete type and\nits descendants are expected to inherit from the interface:\n\n```python\nclass Book(Model):\n    id = Column(UUID, primary_key=True)\n\n\nclass Novel(Book):\n    pass\n\n\nclass ShortStory(Book):\n    pass\n\n\n# in another file\nstrawberry_sqlalchemy_mapper = StrawberrySQLAlchemyMapper()\n\n\n@strawberry_sqlalchemy_mapper.interface(models.Book)\nclass BookInterface:\n    pass\n\n\n@strawberry_sqlalchemy_mapper.type(models.Book)\nclass Book:\n    pass\n\n\n@strawberry_sqlalchemy_mapper.type(models.Novel)\nclass Novel:\n    pass\n\n\n@strawberry_sqlalchemy_mapper.type(models.ShortStory)\nclass ShortStory:\n    pass\n```\n\n## Contributing\n\nWe encourage you to contribute to strawberry-sqlalchemy-mapper! Any contributions you make are greatly appreciated.\n\nIf you have a suggestion that would make this better, please fork the repo and create a pull request. Don't forget to give the project a star! Thanks again!\n\n1. Fork the Project\n2. Create your Feature Branch (git checkout -b feature)\n3. Commit your Changes (git commit -m 'Add some feature')\n4. Push to the Branch (git push origin feature)\n5. Open a Pull Request\n\n\n### Prerequisites\n\nThis project uses `pre-commit`_, please make sure to install it before making any\nchanges::\n\n    pip install pre-commit\n    cd strawberry-sqlalchemy-mapper\n    pre-commit install\n\nIt is a good idea to update the hooks to the latest version::\n\n    pre-commit autoupdate\n\nDon't forget to tell your contributors to also install and use pre-commit.\n\n### Installation\n\n```bash\npip install -r requirements.txt\n```\n\nInstall [PostgreSQL 14+](https://www.postgresql.org/download/)\n\n### Test\n\n```bash\npytest\n```\n\n## \u2696\ufe0f LICENSE\n\nMIT \u00a9 [strawberry-sqlalchemy-mapper](LICENSE.txt)\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "A library for autogenerating Strawberry GraphQL types from SQLAlchemy models.",
    "version": "0.5.0",
    "project_urls": {
        "Changelog": "https://strawberry.rocks/changelog",
        "Discord": "https://discord.com/invite/3uQ2PaY",
        "Documentation": "https://strawberry.rocks/",
        "Homepage": "https://strawberry.rocks/",
        "Mastodon": "https://farbun.social/@strawberry",
        "Repository": "https://github.com/strawberry-graphql/strawberry-sqlalchemy",
        "Sponsor on GitHub": "https://github.com/sponsors/strawberry-graphql",
        "Sponsor on Open Collective": "https://opencollective.com/strawberry-graphql",
        "Twitter": "https://twitter.com/strawberry_gql"
    },
    "split_keywords": [
        "graphql",
        " sqlalchemy",
        " strawberry"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "5269948062fcdf747c73a6792950569d7e5f813590d8ac0396c93cffc2093035",
                "md5": "af2ae38bc2826940f72b1e894c30d7e9",
                "sha256": "90278a2a554c5fea78737dce6bfe0ee777fefb3614748472b5ee0fcb4438e3c5"
            },
            "downloads": -1,
            "filename": "strawberry_sqlalchemy_mapper-0.5.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "af2ae38bc2826940f72b1e894c30d7e9",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<4.0,>=3.8",
            "size": 24355,
            "upload_time": "2024-11-12T13:10:42",
            "upload_time_iso_8601": "2024-11-12T13:10:42.297622Z",
            "url": "https://files.pythonhosted.org/packages/52/69/948062fcdf747c73a6792950569d7e5f813590d8ac0396c93cffc2093035/strawberry_sqlalchemy_mapper-0.5.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "945f2b0631d67cc90100ca372dcf4ed29bbf48306108998c7ad417e35fb8d116",
                "md5": "f1efd41af4381616efe533e0f962a67d",
                "sha256": "1b612c339653cdb3f9395890d36d2180251be4dc0357c18e5fc16cb3be226ac9"
            },
            "downloads": -1,
            "filename": "strawberry_sqlalchemy_mapper-0.5.0.tar.gz",
            "has_sig": false,
            "md5_digest": "f1efd41af4381616efe533e0f962a67d",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<4.0,>=3.8",
            "size": 24596,
            "upload_time": "2024-11-12T13:10:43",
            "upload_time_iso_8601": "2024-11-12T13:10:43.981977Z",
            "url": "https://files.pythonhosted.org/packages/94/5f/2b0631d67cc90100ca372dcf4ed29bbf48306108998c7ad417e35fb8d116/strawberry_sqlalchemy_mapper-0.5.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-11-12 13:10:43",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "strawberry-graphql",
    "github_project": "strawberry-sqlalchemy",
    "travis_ci": false,
    "coveralls": true,
    "github_actions": true,
    "tox": true,
    "lcname": "strawberry-sqlalchemy-mapper"
}
        
Elapsed time: 0.52996s