# UtilMeta API Framework - Python
<img src="https://utilmeta.com/img/py-intro.png" href="https://utilmeta.com/py" target="_blank" alt="drawing" width="720"/>
**UtilMeta** is a progressive meta-framework for backend applications, which efficiently builds declarative APIs based on the Python type annotation standard, and supports the integration of mainstream Python frameworks as runtime backend
* Homepage: [https://utilmeta.com/py](https://utilmeta.com/py)
* Documentation: [https://docs.utilmeta.com/py/en/](https://docs.utilmeta.com/py/en/)
* Author: <a href="https://github.com/voidZXL" target="_blank">@voidZXL</a>
<a href="https://pypi.org/project/utilmeta/" target="_blank">
<img src="https://img.shields.io/pypi/v/utilmeta" alt="">
</a>
<a href="https://pypi.org/project/utilmeta/" target="_blank">
<img src="https://img.shields.io/pypi/pyversions/utilmeta" alt="">
</a>
<a href="https://github.com/utilmeta/utilmeta-py/blob/main/LICENSE" target="_blank">
<img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="">
</a>
<a href="https://github.com/utilmeta/utilmeta-py/actions?query=branch%3Amain+" target="_blank">
<img src="https://img.shields.io/github/actions/workflow/status/utilmeta/utilmeta-py/test.yaml?branch=main&label=CI" alt="">
</a>
## Installation
```
pip install utilmeta
```
## Core Features
### Declarative Development
Using the declarative power from UtilMeta, you can easily write APIs with auto request validation, efficient ORM queries, and auto OpenAPI document generation
<img src="https://utilmeta.com/img/py.section1.png" href="https://utilmeta.com/py" target="_blank" alt="drawing" width="720"/>
### Progressive Meta Framework
UtilMeta developed a standard that support all major Python web framework like **django**, **flask**, **fastapi** (starlette), **sanic**, **tornado** as runtime backend, and support current projects using these frameworks to develop new API using UtilMeta progressively
<img src="https://utilmeta.com/img/py.section2.png" href="https://utilmeta.com/py" target="_blank" alt="drawing" width="720"/>
### Highly Flexible & Extensible
UtilMeta is highly flexible with a series of plugins including authentication (Session/JWT), CORS, rate limit, retry, and can be extended to support more features.
### Full-lifecycle DevOps Solution
The [UtilMeta Platform](https://utilmeta.com/) provided the full-lifecycle DevOps solution for this framework, the API Docs, Debug, Logs, Monitoring, Alerts, Analytics will all been taken care of in the platform
<img src="https://utilmeta.com/img/py.section3.png" href="https://utilmeta.com/py" target="_blank" alt="drawing" width="720"/>
## Hello World
Create a Python file named `server.py` and write the following code
```python
from utilmeta import UtilMeta
from utilmeta.core import api
import django
class RootAPI(api.API):
@api.get
def hello(self):
return 'world'
service = UtilMeta(
__name__,
name='demo',
backend=django, # or flask / starlette / tornado / sanic
api=RootAPI,
route='/api'
)
app = service.application() # wsgi app
if __name__ == '__main__':
service.run()
```
> You can use `flask`, `starlette`, `sanic`, `tornado` instead of `django` as runtime backend, just install them first and replace them in the demo code
### Run
You can execute this file by python to run the server
```shell
python server.py
```
The following info Implies that the service has live
```
Running on http://127.0.0.1:8000
Press CTRL+C to quit
```
Then we can use our browser to open [http://127.0.0.1:8000/api/hello](http://127.0.0.1:8000/api/hello) to call this API directly, we will see
```
world
```
It means this API works
## Examples
### Declarative RESTful API
Declarative ORM in UtilMeta can handle relational queries concisely without N+1 problem, both sync and async queries are supported
```python
from utilmeta.core import api, orm
from django.db import models
class User(models.Model):
username = models.CharField(max_length=20, unique=True)
class Article(models.Model):
author = models.ForeignKey(User, related_name="articles", on_delete=models.CASCADE)
content = models.TextField()
class UserSchema(orm.Schema[User]):
username: str
articles_num: int = models.Count('articles')
class ArticleSchema(orm.Schema[Article]):
id: int
author: UserSchema
content: str
class ArticleAPI(api.API):
async def get(self, id: int) -> ArticleSchema:
return await ArticleSchema.ainit(id)
```
if you request the ArticleAPI like `GET /article?id=1`, you will get the result like
```python
{
"id": 1,
"author": {
"username": "alice",
"articles_num": 3
},
"content": "hello world"
}
```
This conforms to what you declared, and the OpenAPI docs will be generated automatically
### Migrate
Integrate current django/flask/fastapi/... project with UtilMeta API is as easy as follows
```python
import django
from django.urls import re_path
from django.http.response import HttpResponse
from utilmeta.core import api, response
class CalcAPI(api.API):
@api.get
def add(self, a: int, b: int) -> int:
return a + b
def django_test(request, route: str):
return HttpResponse(route)
urlpatterns = [
re_path('test/(.*)', django_test),
CalcAPI.__as__(django, route='/calc'),
]
```
Integrate with Flask example
```python
from flask import Flask
from utilmeta.core import api, response
app = Flask(__name__)
@app.route("/")
def hello_world():
return "<p>Hello, World!</p>"
class CalcAPI(api.API):
@api.get
def add(self, a: int, b: int) -> int:
return a + b
CalcAPI.__as__(app, route='/calc')
```
## Quick Guide
We have several introductory case tutorials from easy to complex, covering most usage of the framework. You can read and learn in the following order.
1. [BMI Calculation API](https://docs.utilmeta.com/py/en/tutorials/bmi-calc)
2. [User Login & RESTful API](https://docs.utilmeta.com/py/en/tutorials/user-auth)
3. [Realworld Blog Project](https://docs.utilmeta.com/py/en/tutorials/realworld-blog)
4. Websocket Chatroom (coming soon)
If you prefer to learn from a specific feature, you can refer to
* [Handle Request](https://docs.utilmeta.com/py/en/guide/handle-request): How to handle path, query parameters, request body, file upload, request headers and cookies.
* [API Class and Routing](https://docs.utilmeta.com/py/en/guide/api-route) How to use API class mounts to define tree-like API routing, and use hooks to easily reuse code between APIs, handle errors, and template responses.
* [Schema query and ORM](https://docs.utilmeta.com/py/en/guide/schema-query) How to use Schema to declaratively write the CRUD query, and ORM operations required by a RESTful interface.
* [API Authentication](https://docs.utilmeta.com/py/en/guide/auth): How to use Session, JWT, OAuth and other methods to authenticate the request of the interface, get the current request's user and simplify the login operation
* [Config, Run & Deploy](https://docs.utilmeta.com/py/en/guide/config-run): How to configure the run settings, startup, and deployment of a service using features such as declarative environment variables
* [Migrate from current project](https://docs.utilmeta.com/py/en/guide/migration) How to progressively integrate UtilMeta API to an existing backend project or migrate to UtilMeta
## Community
Join our community to build great things together
* [Discord](https://discord.gg/JdmEkFS6dS)
* [X(Twitter)](https://twitter.com/@utilmeta)
* [Reddit](https://www.reddit.com/r/utilmeta)
* [中文讨论区](https://lnzhou.com/channels/utilmeta/community)
## Enterprise Solutions & Support
The UtilMeta team is providing custom solutions and enterprise-level support at
* [https://utilmeta.com/solutions](https://utilmeta.com/solutions)
You can also contact us in [this page](https://utilmeta.com/about#contact)
### Wechat
Contact the creator's wechat for support or join the developers wechat group
<img src="https://utilmeta.com/img/wx_zxl.png" href="https://utilmeta.com/py" target="_blank" alt="drawing" width="240"/>
Raw data
{
"_id": null,
"home_page": null,
"name": "UtilMeta",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "API, RESTful, backend, declarative, meta, orm, progressive, utype, web",
"author": null,
"author_email": "\"Xulin Zhou (voidZXL)\" <zxl@utilmeta.com>",
"download_url": "https://files.pythonhosted.org/packages/0b/37/5d4e737408f6499782427ca1c6d373091fc7e9db98b5f180f6b3ad7fccf6/utilmeta-2.5.2.tar.gz",
"platform": null,
"description": "# UtilMeta API Framework - Python\n<img src=\"https://utilmeta.com/img/py-intro.png\" href=\"https://utilmeta.com/py\" target=\"_blank\" alt=\"drawing\" width=\"720\"/>\n\n\n**UtilMeta** is a progressive meta-framework for backend applications, which efficiently builds declarative APIs based on the Python type annotation standard, and supports the integration of mainstream Python frameworks as runtime backend\n\n* Homepage: [https://utilmeta.com/py](https://utilmeta.com/py)\n* Documentation: [https://docs.utilmeta.com/py/en/](https://docs.utilmeta.com/py/en/)\n* Author: <a href=\"https://github.com/voidZXL\" target=\"_blank\">@voidZXL</a>\n\n\n<a href=\"https://pypi.org/project/utilmeta/\" target=\"_blank\">\n\t<img src=\"https://img.shields.io/pypi/v/utilmeta\" alt=\"\">\n</a>\n<a href=\"https://pypi.org/project/utilmeta/\" target=\"_blank\">\n\t<img src=\"https://img.shields.io/pypi/pyversions/utilmeta\" alt=\"\">\n</a>\n<a href=\"https://github.com/utilmeta/utilmeta-py/blob/main/LICENSE\" target=\"_blank\">\n\t<img src=\"https://img.shields.io/badge/license-Apache%202.0-blue\" alt=\"\">\n</a>\n<a href=\"https://github.com/utilmeta/utilmeta-py/actions?query=branch%3Amain+\" target=\"_blank\">\n\t<img src=\"https://img.shields.io/github/actions/workflow/status/utilmeta/utilmeta-py/test.yaml?branch=main&label=CI\" alt=\"\">\n</a>\n\n## Installation\n```\npip install utilmeta\n```\n\n## Core Features\n\n### Declarative Development\nUsing the declarative power from UtilMeta, you can easily write APIs with auto request validation, efficient ORM queries, and auto OpenAPI document generation\n<img src=\"https://utilmeta.com/img/py.section1.png\" href=\"https://utilmeta.com/py\" target=\"_blank\" alt=\"drawing\" width=\"720\"/>\n### Progressive Meta Framework\nUtilMeta developed a standard that support all major Python web framework like **django**, **flask**, **fastapi** (starlette), **sanic**, **tornado** as runtime backend, and support current projects using these frameworks to develop new API using UtilMeta progressively\n<img src=\"https://utilmeta.com/img/py.section2.png\" href=\"https://utilmeta.com/py\" target=\"_blank\" alt=\"drawing\" width=\"720\"/>\n### Highly Flexible & Extensible\nUtilMeta is highly flexible with a series of plugins including authentication (Session/JWT), CORS, rate limit, retry, and can be extended to support more features.\n\n### Full-lifecycle DevOps Solution\nThe [UtilMeta Platform](https://utilmeta.com/) provided the full-lifecycle DevOps solution for this framework, the API Docs, Debug, Logs, Monitoring, Alerts, Analytics will all been taken care of in the platform\n<img src=\"https://utilmeta.com/img/py.section3.png\" href=\"https://utilmeta.com/py\" target=\"_blank\" alt=\"drawing\" width=\"720\"/>\n## Hello World\n Create a Python file named `server.py` and write the following code \n```python\nfrom utilmeta import UtilMeta\nfrom utilmeta.core import api\nimport django\n\nclass RootAPI(api.API):\n @api.get\n def hello(self):\n return 'world'\n\nservice = UtilMeta(\n __name__,\n name='demo',\n backend=django, # or flask / starlette / tornado / sanic\n api=RootAPI,\n route='/api'\n)\n\napp = service.application() # wsgi app\n\nif __name__ == '__main__':\n service.run()\n```\n\n> You can use `flask`, `starlette`, `sanic`, `tornado` instead of `django` as runtime backend, just install them first and replace them in the demo code\n\n### Run\nYou can execute this file by python to run the server\n```shell\npython server.py\n```\nThe following info Implies that the service has live\n```\nRunning on http://127.0.0.1:8000\nPress CTRL+C to quit\n```\nThen we can use our browser to open [http://127.0.0.1:8000/api/hello](http://127.0.0.1:8000/api/hello) to call this API directly, we will see\n```\nworld\n```\nIt means this API works\n## Examples\n\n### Declarative RESTful API\n\nDeclarative ORM in UtilMeta can handle relational queries concisely without N+1 problem, both sync and async queries are supported\n```python\nfrom utilmeta.core import api, orm\nfrom django.db import models\n\nclass User(models.Model):\n username = models.CharField(max_length=20, unique=True)\n\nclass Article(models.Model):\n author = models.ForeignKey(User, related_name=\"articles\", on_delete=models.CASCADE)\n content = models.TextField()\n\nclass UserSchema(orm.Schema[User]):\n username: str\n articles_num: int = models.Count('articles')\n\nclass ArticleSchema(orm.Schema[Article]):\n id: int\n author: UserSchema\n content: str\n\nclass ArticleAPI(api.API):\n async def get(self, id: int) -> ArticleSchema:\n return await ArticleSchema.ainit(id)\n```\n\nif you request the ArticleAPI like `GET /article?id=1`, you will get the result like\n\n```python\n{\n \"id\": 1,\n \"author\": {\n \"username\": \"alice\",\n \"articles_num\": 3\n },\n \"content\": \"hello world\"\n}\n```\nThis conforms to what you declared, and the OpenAPI docs will be generated automatically\n### Migrate\n\nIntegrate current django/flask/fastapi/... project with UtilMeta API is as easy as follows \n```python\nimport django\nfrom django.urls import re_path\nfrom django.http.response import HttpResponse\nfrom utilmeta.core import api, response\n\nclass CalcAPI(api.API):\n @api.get\n def add(self, a: int, b: int) -> int:\n return a + b\n\ndef django_test(request, route: str):\n return HttpResponse(route)\n\nurlpatterns = [\n re_path('test/(.*)', django_test),\n CalcAPI.__as__(django, route='/calc'),\n]\n```\n\nIntegrate with Flask example\n```python\nfrom flask import Flask\nfrom utilmeta.core import api, response\n\napp = Flask(__name__)\n\n@app.route(\"/\")\ndef hello_world():\n return \"<p>Hello, World!</p>\"\n\nclass CalcAPI(api.API):\n @api.get\n def add(self, a: int, b: int) -> int:\n return a + b\n\nCalcAPI.__as__(app, route='/calc')\n```\n\n## Quick Guide\nWe have several introductory case tutorials from easy to complex, covering most usage of the framework. You can read and learn in the following order.\n\n1. [BMI Calculation API](https://docs.utilmeta.com/py/en/tutorials/bmi-calc)\n2. [User Login & RESTful API](https://docs.utilmeta.com/py/en/tutorials/user-auth)\n3. [Realworld Blog Project](https://docs.utilmeta.com/py/en/tutorials/realworld-blog)\n4. Websocket Chatroom (coming soon)\n\nIf you prefer to learn from a specific feature, you can refer to\n\n* [Handle Request](https://docs.utilmeta.com/py/en/guide/handle-request): How to handle path, query parameters, request body, file upload, request headers and cookies.\n* [API Class and Routing](https://docs.utilmeta.com/py/en/guide/api-route) How to use API class mounts to define tree-like API routing, and use hooks to easily reuse code between APIs, handle errors, and template responses.\n* [Schema query and ORM](https://docs.utilmeta.com/py/en/guide/schema-query) How to use Schema to declaratively write the CRUD query, and ORM operations required by a RESTful interface.\n* [API Authentication](https://docs.utilmeta.com/py/en/guide/auth): How to use Session, JWT, OAuth and other methods to authenticate the request of the interface, get the current request's user and simplify the login operation\n* [Config, Run & Deploy](https://docs.utilmeta.com/py/en/guide/config-run): How to configure the run settings, startup, and deployment of a service using features such as declarative environment variables\n* [Migrate from current project](https://docs.utilmeta.com/py/en/guide/migration) How to progressively integrate UtilMeta API to an existing backend project or migrate to UtilMeta\n\n## Community\nJoin our community to build great things together\n\n* [Discord](https://discord.gg/JdmEkFS6dS)\n* [X(Twitter)](https://twitter.com/@utilmeta)\n* [Reddit](https://www.reddit.com/r/utilmeta)\n* [\u4e2d\u6587\u8ba8\u8bba\u533a](https://lnzhou.com/channels/utilmeta/community)\n\n## Enterprise Solutions & Support\nThe UtilMeta team is providing custom solutions and enterprise-level support at\n\n* [https://utilmeta.com/solutions](https://utilmeta.com/solutions)\n\nYou can also contact us in [this page](https://utilmeta.com/about#contact)\n\n### Wechat\n\nContact the creator's wechat for support or join the developers wechat group\n\n\n<img src=\"https://utilmeta.com/img/wx_zxl.png\" href=\"https://utilmeta.com/py\" target=\"_blank\" alt=\"drawing\" width=\"240\"/>",
"bugtrack_url": null,
"license": "Copyright (c) 2019-present Xulin Zhou (\u5468\u7166\u6797)\n \n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n \n http://www.apache.org/licenses/LICENSE-2.0\n \n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License.",
"summary": "UtilMeta - progressive meta framework for API development in Python",
"version": "2.5.2",
"project_urls": {
"Documentation": "https://docs.utilmeta.com/py/en",
"Homepage": "https://utilmeta.com/py",
"Repository": "https://github.com/utilmeta/utilmeta-py"
},
"split_keywords": [
"api",
" restful",
" backend",
" declarative",
" meta",
" orm",
" progressive",
" utype",
" web"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4e33b35a45084c9649408be70efe13b4c6d041258efb80d879f3ee56ac47afaa",
"md5": "05a6324223225a6c0b41ab27c139c25e",
"sha256": "2acb3da3e7198576ede79f93083e3e333053bd8ad28790bd6042434538ee2ab9"
},
"downloads": -1,
"filename": "utilmeta-2.5.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "05a6324223225a6c0b41ab27c139c25e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 345093,
"upload_time": "2024-04-23T16:28:40",
"upload_time_iso_8601": "2024-04-23T16:28:40.664355Z",
"url": "https://files.pythonhosted.org/packages/4e/33/b35a45084c9649408be70efe13b4c6d041258efb80d879f3ee56ac47afaa/utilmeta-2.5.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0b375d4e737408f6499782427ca1c6d373091fc7e9db98b5f180f6b3ad7fccf6",
"md5": "28c95b9c1d1d56c337ac0ebd87182573",
"sha256": "a406875c3bf66acdd021374455bd3d7d4166d6c58beef85a05cc17bb172f8433"
},
"downloads": -1,
"filename": "utilmeta-2.5.2.tar.gz",
"has_sig": false,
"md5_digest": "28c95b9c1d1d56c337ac0ebd87182573",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 250529,
"upload_time": "2024-04-23T16:28:45",
"upload_time_iso_8601": "2024-04-23T16:28:45.107466Z",
"url": "https://files.pythonhosted.org/packages/0b/37/5d4e737408f6499782427ca1c6d373091fc7e9db98b5f180f6b3ad7fccf6/utilmeta-2.5.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-23 16:28:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "utilmeta",
"github_project": "utilmeta-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "utilmeta"
}
JSON
