Skip to content

Commit b23114d

Browse files
monokatarinaCkk3
monokatarina
and
Ckk3
authored
Update README.md - Enhanced Documentation (#242)
* Atualizar o README.md * Atualizar o README.md * Update README.md * Update README.md * Update README.md plz input url * Update README.md Co-authored-by: Luis Gustavo <[email protected]> * Apply suggestions from code review Co-authored-by: Luis Gustavo <[email protected]> * Update README.md * Bring back old examples and add new sections * fix typo and downloads url * update downloads badge to use monthly numbers * add a table of contents and add a url to the main project * fix enum description and add a docs reference * Change limitaions link to supported-types --------- Co-authored-by: Luis Gustavo <[email protected]>
1 parent d162082 commit b23114d

File tree

1 file changed

+89
-32
lines changed

1 file changed

+89
-32
lines changed

‎README.md

Lines changed: 89 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,59 @@
1-
# strawberry-sqlalchemy-mapper
1+
# Strawberry SQLAlchemy Mapper
22

33

4-
Strawberry-sqlalchemy-mapper is the simplest way to implement autogenerated strawberry types for columns and relationships in SQLAlchemy models.
4+
[![PyPI Version][pypi-badge]][pypi-url]
5+
![python][python-badge]
6+
[![Downloads][downloads-badge]][downloads-url]
7+
[![Test Coverage][coverage-badge]][coverage-url]
8+
[![CI/CD Status][ci-badge]][ci-url]
59

10+
[![Discord][discord-badge]][discord-url]
611

7-
- Instead of manually listing every column and relationship in a SQLAlchemy model, strawberry-sqlalchemy-mapper
12+
The simplest way to implement autogenerated [Strawberry][strawberry-url] types for columns and relationships in SQLAlchemy models.
13+
14+
15+
Instead of manually listing every column and relationship in a SQLAlchemy model, strawberry-sqlalchemy-mapper
816
lets you decorate a class declaration and it will automatically generate the necessary strawberry fields
917
for all columns and relationships (subject to the limitations below) in the given model.
1018

11-
- Native support for most of SQLAlchemy's most common types.
19+
20+
- Native support for most of SQLAlchemy's most common types. (See all supported types [here](#supported-types))
1221
- Extensible to arbitrary custom SQLAlchemy types.
1322
- Automatic batching of queries, avoiding N+1 queries when getting relationships
1423
- Support for SQLAlchemy >=1.4.x
1524
- Lightweight and fast.
1625

26+
## Table of Contents
27+
28+
- [Getting Started](#getting-started)
29+
- [Installation](#installation)
30+
- [Basic Usage](#basic-usage)
31+
- [Limitations](#limitations)
32+
- [Supported Types](#supported-types)
33+
- [Association Proxies](#association-proxies)
34+
- [Polymorphic Hierarchies](#polymorphic-hierarchies)
35+
- [Contributing](#contributing)
36+
- [⚖️ LICENSE](#️-license)
37+
38+
1739
## Getting Started
1840

41+
### Installation
1942
strawberry-sqlalchemy-mapper is available on [PyPi](https://pypi.org/project/strawberry-sqlalchemy-mapper/)
2043

2144
```
2245
pip install strawberry-sqlalchemy-mapper
2346
```
2447

48+
### Basic Usage
2549

2650
First, define your sqlalchemy model:
2751

2852
```python
2953
# models.py
30-
from sqlalchemy import Column, Integer, String
54+
from sqlalchemy import Column, ForeignKey, Integer, String
3155
from sqlalchemy.ext.declarative import declarative_base
56+
from sqlalchemy.orm import relationship
3257

3358
Base = declarative_base()
3459

@@ -55,8 +80,9 @@ This will automatically add fields for the model's columns, relationships, assoc
5580
and hybrid properties. For example:
5681

5782
```python
58-
# elsewhere
83+
# In another file
5984
# ...
85+
import strawberry
6086
from strawberry_sqlalchemy_mapper import StrawberrySQLAlchemyMapper
6187

6288
strawberry_sqlalchemy_mapper = StrawberrySQLAlchemyMapper()
@@ -76,6 +102,7 @@ class Department:
76102
class Query:
77103
@strawberry.field
78104
def departments(self):
105+
# This db.session was created with sqlalchemy.orm.sessionmaker(...)
79106
return db.session.scalars(select(models.Department)).all()
80107

81108

@@ -127,45 +154,60 @@ query {
127154

128155
## Limitations
129156

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

134162
Natively supports the following SQLAlchemy types:
135163

136-
```python
137-
Integer: int,
138-
Float: float,
139-
BigInteger: BigInt,
140-
Numeric: Decimal,
141-
DateTime: datetime,
142-
Date: date,
143-
Time: time,
144-
String: str,
145-
Text: str,
146-
Boolean: bool,
147-
Unicode: str,
148-
UnicodeText: str,
149-
SmallInteger: int,
150-
SQLAlchemyUUID: uuid.UUID,
151-
VARCHAR: str,
152-
ARRAY[T]: List[T] # PostgreSQL array
153-
JSON: JSON # SQLAlchemy JSON
154-
Enum: (the Python enum it is mapped to, which should be @strawberry.enum-decorated)
155-
```
164+
165+
| SQLAlchemy Type | Strawberry Equivalent | Notes |
166+
|-----------------------|---------------------------|------------------------|
167+
| `Integer` | `int` | |
168+
| `Float` | `float` | |
169+
| `BigInteger` | `BigInt` | |
170+
| `Numeric` | `Decimal` | |
171+
| `DateTime` | `datetime` | |
172+
| `Date` | `date` | |
173+
| `Time` | `time` | |
174+
| `String` | `str` | |
175+
| `Text` | `str` | |
176+
| `Boolean` | `bool` | |
177+
| `Unicode` | `str` | |
178+
| `UnicodeText` | `str` | |
179+
| `SmallInteger` | `int` | |
180+
| `SQLAlchemyUUID` | `uuid.UUID` | |
181+
| `VARCHAR` | `str` | |
182+
| `ARRAY[T]` | `List[T]` | PostgreSQL array |
183+
| `JSON` | `JSON` | SQLAlchemy JSON |
184+
| `Enum` | `enum.Enum` | The Python enum that the column is mapped to must be decorated with`@strawberry.enum` ([strawberry enum docs][strawberry-enum-docs-url]) |
185+
186+
156187

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

191+
### Association Proxies
192+
160193
Association proxies are expected to be of the form `association_proxy('relationship1', 'relationship2')`,
161194
i.e., both properties are expected to be relationships.
195+
If your `association_proxy` does not follow the expected form, you should add it to `__exclude__` to prevent an exception from being raised.
196+
197+
### Polymorphic Hierarchies
162198

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

167203
```python
168-
class Book(Model):
204+
# models.py
205+
from sqlalchemy import Column
206+
207+
Base = declarative_base()
208+
209+
210+
class Book(Base):
169211
id = Column(UUID, primary_key=True)
170212

171213

@@ -213,24 +255,23 @@ If you have a suggestion that would make this better, please fork the repo and c
213255
4. Push to the Branch (git push origin feature)
214256
5. Open a Pull Request
215257

216-
For more details on how to contribute, as well as how to setup the project on your local machine, please refer to [the docs](CONTRIBUTING.rst)
258+
For more details on how to contribute, as well as how to setup the project on your local machine, please refer to [the contributing docs](CONTRIBUTING.rst)
217259

218260

219261
### Prerequisites
220262

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

224266
pip install pre-commit
225267
cd strawberry-sqlalchemy-mapper
226268
pre-commit install
227269

228-
It is a good idea to update the hooks to the latest version::
229-
230-
pre-commit autoupdate
231270

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

273+
>💡 Tip: You can also use our DevContainer setup for a fully configured development environment, including pre-commit, Python, PostgreSQL, and all required dependencies. This is the fastest way to get started.
274+
234275
### Installation
235276

236277
```bash
@@ -248,3 +289,19 @@ pytest
248289
## ⚖️ LICENSE
249290

250291
MIT © [strawberry-sqlalchemy-mapper](LICENSE.txt)
292+
293+
<!-- Badge Links -->
294+
[pypi-badge]: https://img.shields.io/pypi/v/strawberry-sqlalchemy-mapper?color=blue
295+
[pypi-url]: https://pypi.org/project/strawberry-sqlalchemy-mapper/
296+
[python-badge]: https://img.shields.io/pypi/pyversions/strawberry-sqlalchemy-mapper
297+
[downloads-badge]: https://static.pepy.tech/badge/strawberry-sqlalchemy-mapper/month
298+
[downloads-url]: https://pepy.tech/projects/strawberry-sqlalchemy-mapper
299+
[ci-badge]: https://img.shields.io/github/actions/workflow/status/strawberry-graphql/strawberry-sqlalchemy/test.yml?branch=main
300+
[ci-url]: https://github.com/strawberry-graphql/strawberry-sqlalchemy/actions
301+
[coverage-badge]: https://codecov.io/gh/strawberry-graphql/strawberry-sqlalchemy/branch/main/graph/badge.svg
302+
[coverage-url]: https://codecov.io/gh/strawberry-graphql/strawberry-sqlalchemy
303+
[issues-url]: https://github.com/strawberry-graphql/strawberry-sqlalchemy/issues
304+
[discord-badge]: https://img.shields.io/discord/689806334337482765?label=discord&logo=discord&logoColor=white&style=for-the-badge&color=blue
305+
[discord-url]: https://discord.gg/ZkRTEJQ
306+
[strawberry-url]: https://strawberry.rocks/
307+
[strawberry-enum-docs-url]: https://strawberry.rocks/docs/types/enums#enums

0 commit comments

Comments
 (0)