# Platformics
Platformics is a GraphQL API framework that relies on code generation to implement a full featured GraphQL API on top of a PostgreSQL database, with support for authorization policy enforcement and file persistence via S3. It's built on top of the best available Python tools and frameworks!
The libraries and tools that make Platformics work:
### Links to these tools/libraries
- [LinkML](https://linkml.io/) - Schema modeling language
- [FastAPI](https://fastapi.tiangolo.com/) - Async HTTP router
- [Strawberry](https://strawberry.rocks/) - GraphQL Framework
- [Pydantic](https://docs.pydantic.dev/latest/) - Data validation
- [Cerbos](https://www.cerbos.dev/) - Authorization
- [SQLAlchemy](https://www.sqlalchemy.org/) - Database Access / ORM
- [factory_boy](https://factoryboy.readthedocs.io/en/stable/) - Test fixtures
- [Alembic](https://alembic.sqlalchemy.org/en/latest/) - Database migrations
## Current Features
- [x] Express your schema in a straightforward YAML format
- [x] GraphQL Dataloader pattern (no n+1 queries!)
- [x] Authorization policy enforcement
- [x] Flexible Filtering
- [x] Data aggregation
- [x] Top-level pagination
- [x] Relationship traversal
- [x] DB migrations
- [x] Generated Test fixtures
- [x] pytest wiring
- [x] VSCode debugger integration
- [x] Authorized S3 file up/downloads
- [x] Add custom REST endpoints to generated API
- [x] Add custom GQL queries/mutations to generated API
## Roadmap
- [ ] Plugin hooks to add business logic to generated GQL resolvers
- [ ] Support arbitrary class inheritance hierarchies
- [ ] Package and publish to PyPI
## How to set up your own platformics API
1. Copy the test_app boilerplate code to your own repository.
2. Edit `schema/schema.yml` to reflect your application's data model.
3. Run `make build` and then `make init` to build and run your own GraphQL API service.
4. Browse to http://localhost:9009/graphql to interact with your api!
5. Run `make token` to generate an authorization token that you can use to interact with the API. The `make` target copies the necessary headers to the system clipboard. Paste the token into the `headers` section at the bottom of the GraphQL explorer API
## Versioning platformics
Platformics can be used in downstream applications by
1) using the platformics image as the base Docker image. To select a version of platformics, add the appropriate version tags to the docker image
2) installing as a dependency, `pip install platformics`.
The version in `pyproject.toml` is managed using [poetry-dynamic-versioning](https://pypi.org/project/poetry-dynamic-versioning/) which determines version based on git tags.
## Iterating on your schema
1. Make changes to `schema/schema.yml`
2. Run `make codegen` to re-run code gen and restart the API service
3. If your changes require DB schema changes, run `make alembic-autogenerate` and `make alembic-upgrade-head` to generate DB migrations and run them.
## HOWTO
- [Work with platformics](docs/HOWTO-working-with-platformics.md)
- [Extend the generated API](docs/HOWTO-extend-generated-api.md)
- [Customize Codegen templates](docs/HOWTO-customize-templates.md)
## Contributing
This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to opensource@chanzuckerberg.com.
## Reporting Security Issues
Please disclose security issues responsibly by contacting security@chanzuckerberg.com.
Raw data
{
"_id": null,
"home_page": "https://github.com/chanzuckerberg/platformics",
"name": "platformics",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.12",
"maintainer_email": null,
"keywords": "graphql, codegen",
"author": "CZI Team",
"author_email": "opensource@chanzuckerberg.com",
"download_url": "https://files.pythonhosted.org/packages/f0/ac/078cadf3860b77f12cb95f9560da0b2aa6f020d41e2fafc8b5ebf062d752/platformics-0.1.0.tar.gz",
"platform": null,
"description": "# Platformics\n\nPlatformics is a GraphQL API framework that relies on code generation to implement a full featured GraphQL API on top of a PostgreSQL database, with support for authorization policy enforcement and file persistence via S3. It's built on top of the best available Python tools and frameworks!\n\nThe libraries and tools that make Platformics work:\n\n\n \n### Links to these tools/libraries\n - [LinkML](https://linkml.io/) - Schema modeling language\n - [FastAPI](https://fastapi.tiangolo.com/) - Async HTTP router\n - [Strawberry](https://strawberry.rocks/) - GraphQL Framework\n - [Pydantic](https://docs.pydantic.dev/latest/) - Data validation\n - [Cerbos](https://www.cerbos.dev/) - Authorization\n - [SQLAlchemy](https://www.sqlalchemy.org/) - Database Access / ORM\n - [factory_boy](https://factoryboy.readthedocs.io/en/stable/) - Test fixtures\n - [Alembic](https://alembic.sqlalchemy.org/en/latest/) - Database migrations\n\n## Current Features\n- [x] Express your schema in a straightforward YAML format\n- [x] GraphQL Dataloader pattern (no n+1 queries!)\n- [x] Authorization policy enforcement\n- [x] Flexible Filtering\n- [x] Data aggregation\n- [x] Top-level pagination\n- [x] Relationship traversal\n- [x] DB migrations\n- [x] Generated Test fixtures\n- [x] pytest wiring\n- [x] VSCode debugger integration\n- [x] Authorized S3 file up/downloads\n- [x] Add custom REST endpoints to generated API\n- [x] Add custom GQL queries/mutations to generated API\n\n## Roadmap\n- [ ] Plugin hooks to add business logic to generated GQL resolvers\n- [ ] Support arbitrary class inheritance hierarchies\n- [ ] Package and publish to PyPI\n\n## How to set up your own platformics API\n1. Copy the test_app boilerplate code to your own repository.\n2. Edit `schema/schema.yml` to reflect your application's data model.\n3. Run `make build` and then `make init` to build and run your own GraphQL API service.\n4. Browse to http://localhost:9009/graphql to interact with your api!\n5. Run `make token` to generate an authorization token that you can use to interact with the API. The `make` target copies the necessary headers to the system clipboard. Paste the token into the `headers` section at the bottom of the GraphQL explorer API\n\n## Versioning platformics\nPlatformics can be used in downstream applications by \n1) using the platformics image as the base Docker image. To select a version of platformics, add the appropriate version tags to the docker image\n2) installing as a dependency, `pip install platformics`.\n\nThe version in `pyproject.toml` is managed using [poetry-dynamic-versioning](https://pypi.org/project/poetry-dynamic-versioning/) which determines version based on git tags.\n\n## Iterating on your schema\n1. Make changes to `schema/schema.yml`\n2. Run `make codegen` to re-run code gen and restart the API service\n3. If your changes require DB schema changes, run `make alembic-autogenerate` and `make alembic-upgrade-head` to generate DB migrations and run them.\n\n## HOWTO\n- [Work with platformics](docs/HOWTO-working-with-platformics.md)\n- [Extend the generated API](docs/HOWTO-extend-generated-api.md)\n- [Customize Codegen templates](docs/HOWTO-customize-templates.md)\n\n## Contributing\nThis project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to opensource@chanzuckerberg.com.\n\n## Reporting Security Issues\nPlease disclose security issues responsibly by contacting security@chanzuckerberg.com.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Codegen Python GraphQL Entity Framework",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/chanzuckerberg/platformics",
"Repository": "https://github.com/chanzuckerberg/platformics"
},
"split_keywords": [
"graphql",
" codegen"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8f692922765e8efcfeef21ed6d9f5a6b1469b0c288b5d457323dfd58c12b3df3",
"md5": "d0d0a5e849d477897121d1d5343e3c6b",
"sha256": "41f2fe616c33229557cd9732d780439bd1a469f4baeda468d8ea00bb1bd3a5a5"
},
"downloads": -1,
"filename": "platformics-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d0d0a5e849d477897121d1d5343e3c6b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.12",
"size": 78707,
"upload_time": "2024-08-23T21:01:16",
"upload_time_iso_8601": "2024-08-23T21:01:16.167189Z",
"url": "https://files.pythonhosted.org/packages/8f/69/2922765e8efcfeef21ed6d9f5a6b1469b0c288b5d457323dfd58c12b3df3/platformics-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f0ac078cadf3860b77f12cb95f9560da0b2aa6f020d41e2fafc8b5ebf062d752",
"md5": "e53214f1047cdd3ebfc88357e7e366c2",
"sha256": "a5370199fa568425603d51c0e611ac3c1b8577ec9096d7e2afa5f93b18fcba0a"
},
"downloads": -1,
"filename": "platformics-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "e53214f1047cdd3ebfc88357e7e366c2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 59027,
"upload_time": "2024-08-23T21:01:17",
"upload_time_iso_8601": "2024-08-23T21:01:17.775481Z",
"url": "https://files.pythonhosted.org/packages/f0/ac/078cadf3860b77f12cb95f9560da0b2aa6f020d41e2fafc8b5ebf062d752/platformics-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-23 21:01:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "chanzuckerberg",
"github_project": "platformics",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "platformics"
}
JSON
