# 🔥🔥🔥 Cloudoll
Quickly create web applications based on Python.
## Documentation
[Docs](https://cloudoll.chuchur.com)
[Structure](https://cloudoll.chuchur.com/structure)
[Config](https://cloudoll.chuchur.com/config)
[Middleware](https://cloudoll.chuchur.com/middleware)
[Router](https://cloudoll.chuchur.com/router)
[View](https://cloudoll.chuchur.com/view)
[Cookie and Session](https://cloudoll.chuchur.com/session-cookie)
[Upload file](https://cloudoll.chuchur.com/file-uploads)
[WebSocket](https://cloudoll.chuchur.com/websockets)
[Mysql](https://cloudoll.chuchur.com/mysql)
[Deployment](https://cloudoll.chuchur.com/deployment)
## Install
```sh
pip install cloudoll
```
## Environment
- Operating System: Supports macOS, Linux, Windows
- Runtime Environment: Minimum requirement 3.6.0.
## Quick Start
Now you can use `cloudoll create myapp` to create a new project, 3 steps to start:
1. create a new project
```sh
$ cloudoll create myapp
```
2. cd to project directory
```sh
$ cd myapp
```
3. start dev server
```sh
cloudoll start -n myapp
```
You can also manually create a project step by step.
```sh
$ mkdir cloudoll-demo && cd cloudoll-demo
$ pip3 install cloudoll
$ vi app.py
```
`app.py` content:
```python
## /app.py
from cloudoll.web import app
if __name__ == "__main__":
app.create().run()
```
### Controller
```sh
$ mkdir -p controllers/home
$ touch controllers/home/__init__.py
$ vi controllers/home/index.py
```
`controllers/home/index.py` content:
```python
# /controllers/home/index.py
from cloudoll.web import get
@get('/')
async def home():
return {"name": "cloudoll" ,"msg": "ok"}
```
run:
```sh
$ python3 app.py
$ open http://localhost:9001
```
Open in browser [http://127.0.0.1:9001/](http://127.0.0.1:9001/)
you can see the result:
```json
{
"name": "cloudoll" ,
"msg": "ok" ,
"timestamp": 1681993906410
}
```
Congratulations, you have successfully written one `Restful API` with `cloudoll`.
### Template rendering
In most cases, we need to read the data, render the template, and then present it to the user. Therefore, we need to introduce the corresponding template engine.
in this demo，we using [Nunjucks](https://mozilla.github.io/nunjucks/) to render template.
```sh
$ mkdir templates
$ vi templates/index.html
```
`index.html` contents:
```html
<!-- /templates/index.html -->
<!DOCTYPE html>
<html lang="zh">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Home</title>
</head>
<body>
<p>Hello {{name}}</p>
</body>
</html>
```
edit `/controllers/home/index.py` contents:
```python
# /controllers/home/index.py
from cloudoll.web import get, render_view
@get('/')
async def home():
data = {"name": "cloudoll" ,"msg": "ok"}
return render_view("index.html",data)
```
at this time ,we can see `“Hello cloudoll.`
ok , we wrotten a view page.
### static files
We want to embed static resources such as images, JS, and CSS in the template, which requires the use of static resources. We place these `js`, `css`, and `image` files in the `static` directory.
For online environments, it is recommended to deploy to a CDN or use servers like `nginx`.
```sh
$ mkdir -p static/img
$ mkdir -p static/js
$ mkdir -p static/css
```
in `img` directory ,we can put images resources.
make a new js file `index.js` ,contents:
clike the body , we can see the alert tip "hello world"
```js
// /static/js/index.js
document.addEventListener('DOMContentLoaded',function(){
document.body.addEventListener('click',function(){
alert('hello cloudoll.')
})
})
```
make a new css file `index.css` ,contents:
```css
/* /static/css/index.css */
html,
body {
width: 100%;
height: 100%;
color: rgb(0, 229, 255);
margin: 0;
padding: 0;
}
```
edit the view page `/templates/index.html` ,in `head` we import the css file, like this:
```html
<!-- /templates/index.html -->
<!DOCTYPE html>
<html lang="zh">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="icon" type="image/png" href="/static/img/logo.png"/>
<link rel="stylesheet" href="/static/css/index.css">
<script src="/static/js/index.js"></script>
<title>Home</title>
</head>
<body>
<p>My name is {{name}}</p>
</body>
</html>
```
we create a config file, and config static resource.
```sh
$ mkdir config
$ vi config/conf.local.yaml
```
`/config/conf.local.yaml` contents:
```yaml
server:
static:
prefix: /static
```
after reload the page , our changes will be reflected.
### Middleware
Suppose there is a requirement: our news site prohibits access by Baidu crawlers.
so we need to write a middleware to check User-Agent. like this:
```sh
$ mkdir middlewares
$ vi middlewares/robot.py
```
edit `middlewares/robot.py`, contents:
```python
# /middlewares/robot.py
from cloudoll.web import middleware, render_json
import re
@middleware()
def mid_robot():
async def robot(request, handler):
ua = request.headers.get('user-agent')
if re.match('Baiduspider', ua):
return render_json(status=403, text="Go away , robot.")
return await handler(request)
return robot
```
after restart the server, you can use `curl http://localhost:9001/news -A "Baiduspider"` to see the effect.
we can see more information in [Middleware](https://cloudoll.chuchur.com/middleware)
### Configuration
When writing business logic, it is inevitable to have configuration files. Managing configurations through code involves adding configurations for multiple environments within the code, and passing the parameter of the current environment during startup.
cloudoll support loading configurations based on the environment, defining configuration files for multiple environments
```ini
config
|- conf.local.yaml
|- conf.prod.yaml
`- conf.test.yaml
```
now, we create a config file:
```sh
$ mkdir -p config/conf.local.yaml
$ vi config/conf.local.yaml
```
the flollowing is mysql and server's configuration:
```yaml
server:
host: 192.168.0.1
port: 9001
static: false
client_max_size: 1024000
static:
prefix: /static
show_index: true
append_version: true
follow_symlinks: true
database:
mysql:
host: 127.0.0.1
port: 3306
user: root
password: abcd
db: blog
charset: utf8mb4
```
the `local` will be used as default configuration, when you start your application, it will load the `local` configuration. like `cloudoll start -n myapp -env local` will load the `conf.local.yaml` configuration.
# cli
## Create model
export model from database
```sh
cloudoll gen -t users
```
More parameters:
- -p (--path) the path to save the model
- -c (--create) to create model or create tables, default is create model
- -t (--table) The model or table name to be generated, separated by `,`, `ALL` for all tables
- -env (--environment) to load the configuration file , default is `local`
- -db (--database) Database instance name, depends on the configuration file, if there are multiple databases
- -h (--help) help
## Development and debugging
```sh
cloudoll start --name myapp -env local -m development
```
## Production Environment
```sh
cloudoll start --name myapp -env prod --mode production
```
you can use `clodoll stop myapp` to stop your application ,
or use `cloudoll restart myapp` to restart your application.
`cloudoll list` to see all your applications.
Raw data
{
"_id": null,
"home_page": "https://github.com/smallerqiu/cloudoll-py",
"name": "cloudoll",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6.0",
"maintainer_email": null,
"keywords": "Microservices, aiohttp, cloudoll",
"author": "Qiu",
"author_email": "Qiu <smallerqiu@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/44/f8/b5fe3db9330227d1def5d97235aac8fadede6298e3357ef3d6a20005d36d/cloudoll-3.0.3.tar.gz",
"platform": null,
"description": "# \ud83d\udd25\ud83d\udd25\ud83d\udd25 Cloudoll\nQuickly create web applications based on Python.\n\n## Documentation\n\n[Docs](https://cloudoll.chuchur.com)\n\n[Structure](https://cloudoll.chuchur.com/structure)\n\n[Config](https://cloudoll.chuchur.com/config)\n\n[Middleware](https://cloudoll.chuchur.com/middleware)\n\n[Router](https://cloudoll.chuchur.com/router)\n\n[View](https://cloudoll.chuchur.com/view)\n\n[Cookie and Session](https://cloudoll.chuchur.com/session-cookie)\n\n[Upload file](https://cloudoll.chuchur.com/file-uploads)\n\n[WebSocket](https://cloudoll.chuchur.com/websockets)\n\n[Mysql](https://cloudoll.chuchur.com/mysql)\n\n[Deployment](https://cloudoll.chuchur.com/deployment)\n\n## Install\n```sh\npip install cloudoll\n\n```\n\n## Environment \n\n- Operating System: Supports macOS, Linux, Windows\n- Runtime Environment: Minimum requirement 3.6.0.\n\n## Quick Start\n\nNow you can use `cloudoll create myapp` to create a new project, 3 steps to start:\n\n1. create a new project\n```sh\n$ cloudoll create myapp\n```\n2. cd to project directory\n```sh\n$ cd myapp\n```\n3. start dev server\n```sh\ncloudoll start -n myapp\n```\nYou can also manually create a project step by step. \n\n```sh\n$ mkdir cloudoll-demo && cd cloudoll-demo\n$ pip3 install cloudoll\n$ vi app.py\n```\n\n`app.py` content:\n\n```python\n## /app.py\nfrom cloudoll.web import app\n\n\nif __name__ == \"__main__\":\n app.create().run()\n```\n\n### Controller\n\n```sh\n$ mkdir -p controllers/home\n$ touch controllers/home/__init__.py\n$ vi controllers/home/index.py\n```\n\n`controllers/home/index.py` content:\n\n```python\n# /controllers/home/index.py\nfrom cloudoll.web import get\n\n@get('/')\nasync def home():\n return {\"name\": \"cloudoll\" ,\"msg\": \"ok\"}\n```\n\nrun:\n```sh\n$ python3 app.py\n$ open http://localhost:9001\n```\n\nOpen in browser [http://127.0.0.1:9001/](http://127.0.0.1:9001/)\n\nyou can see the result:\n\n```json\n{ \n \"name\": \"cloudoll\" ,\n \"msg\": \"ok\" ,\n \"timestamp\": 1681993906410 \n}\n```\n\nCongratulations, you have successfully written one `Restful API` with `cloudoll`. \n\n\n### Template rendering\n\nIn most cases, we need to read the data, render the template, and then present it to the user. Therefore, we need to introduce the corresponding template engine.\n\nin this demo\uff0cwe using [Nunjucks](https://mozilla.github.io/nunjucks/) to render template.\n```sh\n$ mkdir templates\n$ vi templates/index.html\n```\n\n`index.html` contents:\n\n```html\n<!-- /templates/index.html -->\n\n<!DOCTYPE html>\n<html lang=\"zh\">\n<head>\n <meta charset=\"UTF-8\">\n <meta http-equiv=\"X-UA-Compatible\" content=\"IE=edge\">\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n <title>Home</title>\n</head>\n<body>\n <p>Hello {{name}}</p>\n</body>\n</html>\n```\n\n\nedit `/controllers/home/index.py` contents:\n\n```python\n# /controllers/home/index.py\nfrom cloudoll.web import get, render_view\n\n@get('/')\nasync def home():\n data = {\"name\": \"cloudoll\" ,\"msg\": \"ok\"}\n return render_view(\"index.html\",data)\n```\n\nat this time ,we can see `\u201cHello cloudoll.`\n\nok , we wrotten a view page.\n\n### static files\n\nWe want to embed static resources such as images, JS, and CSS in the template, which requires the use of static resources. We place these `js`, `css`, and `image` files in the `static` directory.\n\nFor online environments, it is recommended to deploy to a CDN or use servers like `nginx`.\n\n```sh\n$ mkdir -p static/img\n$ mkdir -p static/js\n$ mkdir -p static/css\n```\nin `img` directory ,we can put images resources.\n\nmake a new js file `index.js` ,contents:\n\nclike the body , we can see the alert tip \"hello world\"\n```js\n// /static/js/index.js\ndocument.addEventListener('DOMContentLoaded',function(){\n document.body.addEventListener('click',function(){\n alert('hello cloudoll.')\n })\n})\n```\nmake a new css file `index.css` ,contents:\n```css\n /* /static/css/index.css */\nhtml,\nbody {\n width: 100%;\n height: 100%;\n color: rgb(0, 229, 255);\n margin: 0;\n padding: 0;\n}\n```\n\nedit the view page `/templates/index.html` ,in `head` we import the css file, like this:\n\n```html\n<!-- /templates/index.html -->\n<!DOCTYPE html>\n<html lang=\"zh\">\n<head>\n <meta charset=\"UTF-8\">\n <meta http-equiv=\"X-UA-Compatible\" content=\"IE=edge\">\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n <link rel=\"icon\" type=\"image/png\" href=\"/static/img/logo.png\"/>\n <link rel=\"stylesheet\" href=\"/static/css/index.css\">\n <script src=\"/static/js/index.js\"></script>\n <title>Home</title>\n</head>\n<body>\n <p>My name is {{name}}</p>\n</body>\n</html>\n```\n\nwe create a config file, and config static resource.\n```sh\n$ mkdir config\n$ vi config/conf.local.yaml\n```\n\n`/config/conf.local.yaml` contents:\n\n```yaml\nserver:\n static:\n prefix: /static\n```\n\nafter reload the page , our changes will be reflected.\n\n### Middleware\n\nSuppose there is a requirement: our news site prohibits access by Baidu crawlers.\n\nso we need to write a middleware to check User-Agent. like this:\n\n```sh\n$ mkdir middlewares\n$ vi middlewares/robot.py\n```\n\nedit `middlewares/robot.py`, contents:\n\n```python\n# /middlewares/robot.py\nfrom cloudoll.web import middleware, render_json\nimport re\n\n@middleware()\ndef mid_robot():\n async def robot(request, handler):\n ua = request.headers.get('user-agent')\n if re.match('Baiduspider', ua):\n return render_json(status=403, text=\"Go away , robot.\")\n return await handler(request)\n\n return robot\n```\nafter restart the server, you can use `curl http://localhost:9001/news -A \"Baiduspider\"` to see the effect.\nwe can see more information in [Middleware](https://cloudoll.chuchur.com/middleware)\n\n### Configuration\nWhen writing business logic, it is inevitable to have configuration files. Managing configurations through code involves adding configurations for multiple environments within the code, and passing the parameter of the current environment during startup.\n\ncloudoll support loading configurations based on the environment, defining configuration files for multiple environments\n\n```ini\nconfig\n|- conf.local.yaml\n|- conf.prod.yaml\n`- conf.test.yaml\n```\n\nnow, we create a config file:\n```sh\n$ mkdir -p config/conf.local.yaml\n$ vi config/conf.local.yaml\n```\n\nthe flollowing is mysql and server's configuration:\n```yaml\nserver:\n host: 192.168.0.1\n port: 9001\n static: false\n client_max_size: 1024000\n static: \n prefix: /static\n show_index: true\n append_version: true\n follow_symlinks: true\ndatabase:\n mysql:\n host: 127.0.0.1\n port: 3306\n user: root\n password: abcd\n db: blog\n charset: utf8mb4\n```\nthe `local` will be used as default configuration, when you start your application, it will load the `local` configuration. like `cloudoll start -n myapp -env local` will load the `conf.local.yaml` configuration.\n\n# cli \n\n## Create model\n\nexport model from database\n```sh\ncloudoll gen -t users \n```\nMore parameters:\n- -p (--path) the path to save the model\n- -c (--create) to create model or create tables, default is create model\n- -t (--table) The model or table name to be generated, separated by `,`, `ALL` for all tables\n- -env (--environment) to load the configuration file , default is `local`\n- -db (--database) Database instance name, depends on the configuration file, if there are multiple databases\n- -h (--help) help\n\n## Development and debugging\n\n```sh\ncloudoll start --name myapp -env local -m development\n```\n\n## Production Environment\n\n```sh\ncloudoll start --name myapp -env prod --mode production\n```\n\nyou can use `clodoll stop myapp` to stop your application ,\nor use `cloudoll restart myapp` to restart your application.\n`cloudoll list` to see all your applications.\n",
"bugtrack_url": null,
"license": null,
"summary": "Assist in quickly creating distributable microservices based on aiohttp, with a focus on simplicity and ease of use.",
"version": "3.0.3",
"project_urls": {
"Homepage": "https://github.com/smallerqiu/cloudoll-py",
"Repository": "https://github.com/smallerqiu/cloudoll-py"
},
"split_keywords": [
"microservices",
" aiohttp",
" cloudoll"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7bac9875f21e6dee834c21f48ac6f62177e59457629b8a27e8ad704708a4476f",
"md5": "21aaa4fa784ff33f1c14661924f3f8c1",
"sha256": "770f12aa41548bc46a4a9b43e12301dfae0844fa938883d4d3e04800a7b565ce"
},
"downloads": -1,
"filename": "cloudoll-3.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "21aaa4fa784ff33f1c14661924f3f8c1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6.0",
"size": 47773,
"upload_time": "2025-07-10T09:51:59",
"upload_time_iso_8601": "2025-07-10T09:51:59.332166Z",
"url": "https://files.pythonhosted.org/packages/7b/ac/9875f21e6dee834c21f48ac6f62177e59457629b8a27e8ad704708a4476f/cloudoll-3.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "44f8b5fe3db9330227d1def5d97235aac8fadede6298e3357ef3d6a20005d36d",
"md5": "a58033e5f29c78387b7ec0d64104be68",
"sha256": "586b3bd51dd40d5a5f38ecd104e08eb52dd07d871e38dd1a510c9f9732f33267"
},
"downloads": -1,
"filename": "cloudoll-3.0.3.tar.gz",
"has_sig": false,
"md5_digest": "a58033e5f29c78387b7ec0d64104be68",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6.0",
"size": 43669,
"upload_time": "2025-07-10T09:52:00",
"upload_time_iso_8601": "2025-07-10T09:52:00.843985Z",
"url": "https://files.pythonhosted.org/packages/44/f8/b5fe3db9330227d1def5d97235aac8fadede6298e3357ef3d6a20005d36d/cloudoll-3.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 09:52:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "smallerqiu",
"github_project": "cloudoll-py",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "aiomysql",
"specs": [
[
"==",
"0.2.0"
]
]
},
{
"name": "aiopg",
"specs": [
[
"==",
"1.4.0"
]
]
},
{
"name": "PyJWT",
"specs": [
[
"==",
"2.10.1"
]
]
},
{
"name": "aiohttp",
"specs": [
[
"==",
"3.12.13"
]
]
},
{
"name": "Jinja2",
"specs": [
[
"==",
"3.1.6"
]
]
},
{
"name": "colorlog",
"specs": [
[
"==",
"6.9.0"
]
]
},
{
"name": "PyYAML",
"specs": [
[
"==",
"6.0.2"
]
]
},
{
"name": "redis",
"specs": [
[
"==",
"5.2.1"
]
]
},
{
"name": "hiredis",
"specs": [
[
"==",
"3.2.0"
]
]
},
{
"name": "aiomcache",
"specs": [
[
"==",
"0.8.2"
]
]
},
{
"name": "aiohttp-session",
"specs": [
[
"==",
"2.12.1"
]
]
},
{
"name": "watchfiles",
"specs": [
[
"==",
"1.1.0"
]
]
},
{
"name": "envyaml",
"specs": [
[
"==",
"1.10.211231"
]
]
},
{
"name": "psutil",
"specs": [
[
"==",
"7.0.0"
]
]
},
{
"name": "tabulate",
"specs": [
[
"==",
"0.9.0"
]
]
},
{
"name": "concurrent_log_handler",
"specs": [
[
"==",
"0.9.28"
]
]
}
],
"lcname": "cloudoll"
}
JSON
