From c699f59ca653af1ba587069c648e32c260bdecde Mon Sep 17 00:00:00 2001 From: Mikhail Kashkin Date: Fri, 9 Aug 2019 09:44:04 +0300 Subject: [PATCH] Update spelling --- README.md | 108 +++++++++++++++++++++++++++--------------------------- 1 file changed, 54 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index 9d76c72..e57f7f6 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,29 @@ # Flask project template -`Flask project template` contains working example of Flask project with features: +`Flask project template` contains a working example of a Flask project with features: - Ready to ship Flask project template - **Database migrations** out-of-the-box (uses Alembic) - Simple setup `make setup && make run` which make local virtualenv isolated environment and doesn't trash your system python. -- Contains `Dockerfile` that allow to setup full linux environment on any host OS supported by Docker -- Static files managed by `bower`. By default templates uses `Bootstrap` but doesn't force you to use this UI framework. -- Have working example of GitHub **OAuth authorization**, you only need to provide your own security and secret key (will work with example keys only on `127.0.0.1:5000`). Allow user login/logout +- Contains `Dockerfile` that allows to setup full Linux environment on any host OS supported by Docker +- Static files managed by `bower`. By default, templates use `Bootstrap` but don't force you to use this UI framework. +- Have a working example of GitHub **OAuth authorization**, you only need to provide your own security and secret key (will work with example keys only on `127.0.0.1:5000`). Allow user login/logout - **i18n** and **l10n** via integrated Babel support and `make` targets -- User settings page with ability to switch site language +- User settings page with the ability to switch the site language - `Flask-FlatPages` support to simplify static pages management -- Built In `Flask-Script` shell commands +- Built-In `Flask-Script` shell commands - **Fixtures** dump/restore support -- Inegrated [Celery](http://celeryproject.org/) background tasks management +- Integrated [Celery](http://celeryproject.org/) background tasks management - Cache using [Flask-Cache](https://pythonhosted.org/Flask-Cache/) -- Logging with example how to make email notifications when something goes wrong on server +- Logging with an example of how to make email notifications when something goes wrong on the server ## How to start -There is two ways. First way is use [`cookiecutter`](https://github.com/audreyr/cookiecutter) template (it located in [different repository](https://github.com/xen/flask-ptc)): +There are two ways. First way is use [`cookiecutter`](https://github.com/audreyr/cookiecutter) template (it located in [different repository](https://github.com/xen/flask-ptc)): cookiecutter https://github.com/xen/flask-ptc.git -Second way is manually clone this repository and change it later by own. Project is ready to run (with some requrements). You need to clone and run: +The second way is to manually clone this repository and change it later by own. Project is ready to run (with some requirements). You need to clone and run: ```sh $ mkdir Project @@ -35,15 +35,15 @@ $ make run Open http://127.0.0.1:5000/, customize project files and **have fun**. -If you have any ideas how to improve it [Fork project](https://github.com/xen/flask-project-template/fork) and send me pull request. +If you have any ideas about how to improve it [Fork project](https://github.com/xen/flask-project-template/fork) and send me a pull request. ## Requirements -If you never worked with python projects then simpliest way is run project inside Docker. Follow instruction [how to install Docker in your OS](https://docs.docker.com/installation/). +If you never worked with python projects then the simplest way is run project inside Docker. Follow instruction [how to install Docker in your OS](https://docs.docker.com/installation/). If you familiar with web development then you need Python and Node.js: -- Recent Python supported version with sqlite library (usually it is included) -- Working `virtualenv` command, name can vary, so you can change it inside `Makefile` +- Recent Python supported version with SQLite library (usually it is included) +- Working `virtualenv` command, a name can vary, so you can change it inside `Makefile` - `make` - [`bower`](http://bower.io/), if you already have `node.js` with `npm` then run this command: @@ -53,18 +53,18 @@ npm install -g bower ## macOS -How to make full Python setup on macOS is not topic that can be cowered quickly (because you will need XCode and few more steps). One of the prefered ways to install required packages is to use `brew`. Memcached and Redis are not nesessary for all sites, but I have included them into project since my projects usually depends on them. If you need them also then install [`brew`](http://brew.sh) and then run this command: +How to make full Python setup on macOS is not topic that can be cowered quickly (because you will need XCode and few more steps). One of the preferred ways to install required packages is to use `brew`. Memcached and Redis are not necessary for all sites, but I have included them in the project since my projects usually depend on them. If you need them also then install [`brew`](http://brew.sh) and then run this command: ```sh brew install python # or python3 or pypy brew install memcached libmemcached redis ``` -You also can use `brew` to install your prefered RDBMS, nginx or whatever you need for your development. +You also can use `brew` to install your preferred RDBMS, nginx or whatever you need for your development. **Can I use Python 3?** -This Flask project template is Python 3 ready, but unfortunately some of Flask extensions or python modules can be incompatible with Python 3.x. If you are sure that you don't need one of them then try to use Python 3.x or PyPy. +This Flask project template is Python 3 ready, but unfortunately, some of the Flask extensions or python modules can be incompatible with Python 3.x. If you are sure that you don't need one of them then try to use Python 3.x or PyPy. ## Included modules support @@ -73,25 +73,25 @@ This Flask project template is Python 3 ready, but unfortunately some of Flask e - [`Flask-FlatPages`](https://pythonhosted.org/Flask-FlatPages/) with [`Markdown`](https://pythonhosted.org/Markdown/) — to maintain auxiliary pages (About, Contacts, etc). - [`Flask-Script`](http://flask-script.readthedocs.org/) — simplify management tasks. - [`Flask-WTF`](https://flask-wtf.readthedocs.org/) — form validation. -- [`flask-restless`](http://flask-restless.readthedocs.org/) — restfull API generator. +- [`flask-restless`](http://flask-restless.readthedocs.org/) — restful API generator. - [`Flask-SQLAlchemy`](https://pythonhosted.org/Flask-SQLAlchemy/) — database ORM layer build on top of SQLAlchemy, best python ORM with depth and flexibility. - [`flask-migrate`](http://flask-migrate.readthedocs.org/) — database schema migration support. - [`python_social_auth`](https://github.com/omab/python-social-auth) & [`Flask-Login`](https://flask-login.readthedocs.org/) — social networks login. -- [`Celery`](http://celeryproject.org/) — background and defered tasks broker. +- [`Celery`](http://celeryproject.org/) — background and deferred tasks broker. - [`Flask-Cache`](https://pythonhosted.org/Flask-Cache/) — tiny cache extension. Since I found myself using cache in most projects added this package to the list. ## `make` commands overview -There is several useful targets in `Makefile`: +There are several useful targets in `Makefile`: - `setup` — will make local virtualenv environment and install all dependencies including JavaScript libraries in `static` folder - `run` — local run server in DEBUG mode -- `init` — synchronize database scheme and apply migrations. This target should be idempotent (if you run in several times you will get the same results in the end), but if you work with several database at once sometimes in need manual tuning. +- `init` — synchronize database scheme and apply migrations. This target should be idempotent (if you run in several times you will get the same results in the end), but if you work with several databases at once sometimes in need manual tuning. - `babel` and `lazybabel` — generate `project/translations/messages.pot` file with different strategy. - `addlang` — add new language translation with code taken from shell variable `LANG`. Simple usage example `$ LANG=en make addlang` - `updlang` — update language files in language folders made by `addlang` command. - `celery` — run celery broker -- `dcelery` — run celery broker in debug state with code reload and verbose output. Sometimes require manual reloads, but more handy during development +- `dcelery` — run celery broker in debug state with code reload and verbose output. Sometimes require manual reloads, but handier during development Translation workflow in nutshell: @@ -99,48 +99,48 @@ Translation workflow in nutshell: - Run `lazybabel` if new translations strings were added or modified - Run `updlang` to apply master `.pot` files changes to `.po` language files - Run `addlang` if you need to support another language -- Update `project/config.py` `LANGUAGES` dict to allow users see new translations in Settings page +- Update `project/config.py` `LANGUAGES` dict to allow users to see new translations in the Settings page - Use [Poedit](http://poedit.net/) to translate strings ## `manage.py` command overview -`Flask-Script` added flawor of Django `manage.py` to Flask development. Put your common management tasks inside this file. Migration commands already available with `db` prefix. For example how to make new migration and upgrade your database: +`Flask-Script` added flavor of Django `manage.py` to Flask development. Put your common management tasks inside this file. Migration commands already available with `db` prefix. For example how to make new migration and upgrade your database: ```sh $ python manage.py db migrate -m "new models" $ python manage.py db upgrade -# don't forget to add new file under git control +# don't forget to add a new file under git control $ git add migrations/versions/*.py ``` -By default `manage.py` already have this commands: +By default `manage.py` already have these commands: -* `init` — recreate all tables in database. Usually you don't need to use this command since it will erase all your data, but on empty environment can be usefull on local enviroment. +* `init` — recreate all tables in the database. Usually, you don't need to use this command since it will erase all your data, but on the empty environment can be useful in the local environment. * `dump` — make fixture and save all data contained in models defined in `dump_models` variable. -* `restore` — restore fixtures from file created by `dump` command. +* `restore` — restore fixtures from a file created by `dump` command. ## Project structure -After you checkout this code you may need to rename folder `project` to something more relevant your needs. I prefer to have own name for each individual project. Next step to change all mentions of word `project` in your code. I don't added any code generators for this project since anyway make code reviews every time starting new Flask project by adding or removing extensions or some parts of the source code. +After you check out this code you may need to rename folder `project` to something more relevant your needs. I prefer to have own name for each project. Next step to change all mentions of the word `project` in your code. I don't add any code generators for this project since anyway make code reviews every time starting new Flask project by adding or removing extensions or some parts of the source code. . ├── Dockerfile -If you need run project inside `Docker` +If you need to run the project inside `Docker` ├── Makefile ├── README.md ├── babel.cfg -Configuration for `Flask-Babel`, generally you don't need to edit this file unless you use different template system. +Configuration for `Flask-Babel`, generally you don't need to edit this file unless you use a different template system. ├── celery_run.py -To run Celery brocker use this file. +To run Celery broker use this file. ├── entry.py -To run Flask server use this file, it is already prepared for `uwsgi`, `mod_wsgi` or other wsgi webserver modules. +To run Flask server use this file, it is already prepared for `uwsgi`, `mod_wsgi` or other wsgi web server modules. ├── local.example.cfg @@ -162,7 +162,7 @@ Migrations folder contains all your database migrations. ├── packages.txt -This file used by Docker and contains all Ubuntu packages that need to be installed on fresh Ubuntu server. +This file used by Docker and contains all Ubuntu packages that need to be installed on a fresh Ubuntu server. ├── project @@ -173,7 +173,7 @@ Your project code is here │ │ ├── __init__.py │ │ └── views.py -Put here your your admin or API views created by `Flask-Admin` or `Flask-Restless`. +Put here your admin or API views created by `Flask-Admin` or `Flask-Restless`. │ ├── app.py @@ -191,16 +191,16 @@ This cornerstone part of the project structure. But export only two functions `c │ │ │ └── settings.html │ │ └── views.py -`project.auth` is working example of blueprint which show how to organize user authentication using different OAuth providers, such as Facebook, GitHub, Twitter, etc. [Full list of supported social backends](http://psa.matiasaguirre.net/docs/backends/index.html#social-backends) available in `python-social-auth` documentation page. +`project.auth` is working example of blueprint which shows how to organize user authentication using different OAuth providers, such as Facebook, GitHub, Twitter, etc. [Full list of supported social backends](http://psa.matiasaguirre.net/docs/backends/index.html#social-backends) available in `python-social-auth` documentation page. │ ├── config.py -File contains default configuration for the project. My personal approach to have code that can run with defaults. When you don't need special Postgres or other database features on deployment environment for testing purpose enough to use SQLite, but set of projects that are database agnostic is very limited in real life. More about [configuration](#configuration) is separate chapter. +The file contains default configuration for the project. My approach to have code that can run with defaults. When you don't need special Postgres or other database features on deployment environment for testing purpose enough to use SQLite, but a set of projects that are database agnostic is very limited in real life. More about [configuration](#configuration) is separate chapter. │ ├── docs │ │ └── index.md -Have section with simple text files is common for sites. Sometimes you need to have "Contacts" or "Features" page without dynamic elements. Just simple HTML. Here are these files. By default available by `frontend.page` route, if you need to change it see inside [`frontend/views.py`](https://github.com/xen/flask-project-template/blob/master/project/frontend/views.py). +Have a section with simple text files is common for sites. Sometimes you need to have "Contacts" or "Features" page without dynamic elements. Just simple HTML. Here are these files. By default available by `frontend.page` route, if you need to change it see inside [`frontend/views.py`](https://github.com/xen/flask-project-template/blob/master/project/frontend/views.py). │ ├── extensions.py @@ -214,15 +214,15 @@ All Flask extensions registered here. You can access them by import from this fi │ │ │ └── user_profile.html │ │ └── views.py -Front page of the site and some useful common pages combined in one blueprint. Generally each site section have its own blueprint, but if you are not sure where to put something small put it here. +Frontpage of the site and some useful common pages combined in one blueprint. Generally, each site section has its blueprint, but if you are not sure where to put something small put it here. │ ├── models.py -Helper to access `SQLAlchemy` models. I found very comfortably to have all models collected together in one place. Since your models always mapped into database you never should have conflict errors using the same name because database don't allow to have several tables with the same name. +Helper to access `SQLAlchemy` models. I found very comfortable to have all models collected together in one place. Since your models always mapped into the database you never should have conflict errors using the same name because the database doesn't allow to have several tables with the same name. │ ├── tasks.py -Celery tasks placed here. If you have worked with Celery you will found yourself familiar with this concept. If you need to spit tasks in different files then follow idea of `models.py`. +Celery tasks placed here. If you have worked with Celery you will found yourself familiar with this concept. If you need to spit tasks in different files then follow the idea of `models.py`. │ ├── templates │ │ ├── base.html @@ -237,7 +237,7 @@ Celery tasks placed here. If you have worked with Celery you will found yourself │ │ ├── nav.html │ │ └── page.html -There are basic site templates. Each blueprint have its own `template/` folder because of recommendation of Jinja documentation. If you don't want to read how Jinja environment lookup working then just follow this pattern. For your convenience `misc` folder contains templates for common error pages. +There are basic site templates. Each blueprint has it's own `template/` folder because of the recommendation of Jinja documentation. If you don't want to read how Jinja environment lookup working then just follow this pattern. For your convenience `misc` folder contains templates for common error pages. │ ├── translations │ │ ├── en @@ -253,7 +253,7 @@ If you don't need internationalization you can ignore this folder. If you don't │ └── utils.py -Trash-can for all common usefulness that can't find place in other parts of the code. +Trash-can for all common usefulness that can't find a place in other parts of the code. ├── requirements.txt @@ -261,7 +261,7 @@ All project dependencies installed by `pip`. ├── setup.py -This file makes your folder python project that can be wrapped into egg and distributed by DevOps. This part is not covered in documentation and usually needed on past stages of project. +This file makes your folder python project that can be wrapped into an egg and distributed by DevOps. This part is not covered in the documentation and usually needed on past stages of the project. └── static ├── bower.json @@ -271,33 +271,33 @@ This file makes your folder python project that can be wrapped into egg and dist ├── robots.txt └── style.css -All static dependencies are installed by [`bower`](http://bower.io/) packages manager. Of course you can get rid of `node.js` as dependency, but I found that full automation save vast amount of time and it is almost impossible to avoid of using popular JavaScript frameworks or compilers. Why to avoid such things as `browserify` or CoffeScript? By default site already use Bootstrap. +All static dependencies are installed by [`bower`](http://bower.io/) packages manager. Of course, you can get rid of `node.js` as a dependency, but I found that full automation saves a vast amount of time and it is almost impossible to avoid of using popular JavaScript frameworks or compilers. Why avoid such things as `browserify` or CoffeScript? By default site already use Bootstrap. ## Configuration -Already mention my approach: project should be able to start with minimum external dependencies. Of course if project grow up probability of using individual features increase. For example Postgres have different capabilities then SQLite, but this Flask project template trying to be as much agnostic as it can. That is why `config.py` is not empty, I attempt to make you able to start your simple Flask application after git checkout. +Already mention my approach: the project should be able to start with minimum external dependencies. Of course, if the project grows up the probability of using individual features increase. For example, Postgres has different capabilities then SQLite, but this Flask project template trying to be as much agnostic as it can. That is why `config.py` is not empty, I attempt to make you able to start your simple Flask application after git checkout. -Of course you will make changes to your configuration, but more important how your project will work after development phase and how it flexible will be if you have team of developers. +Of course, you will make changes to your configuration, but more importantly how your project will work after the development phase and how it flexible will be if you have a team of developers. My recommendation store everything common and insensitive inside `config.py`. But if you need to have personal settings then store in `local.cfg` and put this file in the root folder of the project. -But still it is not flexible enough. What if you need to connect staging or test database? Then you can use option `-c` to define different config file: +But still, it is not flexible enough. What if you need to connect staging or test database? Then you can use the option `-c` to define different config file: $ python manage.py runserver -c test.cfg - # if you need to apply migration to test database + # if you need to apply the migration to test database $ python manage.py -c test.cfg db upgrade This time Flask will read configuration this order: -1. `config.py` inside project folder -2. Try to find `local.cfg` in parent folder +1. `config.py` inside the project folder +2. Try to find `local.cfg` in the parent folder 3. Configuration file provided by command line -Notice that `cfg` files don't executed it is simple text files. In the end configuration variable will have last value it was mentioned. For example if `MAIL_SERVER` defined in `config.py` and redefined in `local.cfg` then last value will be used by Flask application. +Notice that `cfg` files don't execute it is simple text files. In the end configuration variable will have the last value it was mentioned. For example if `MAIL_SERVER` defined in `config.py` and redefined in `local.cfg` then the last value will be used by Flask application. -This approach cover most cases I have in my practice. Show your DevOp how to use `cfg` and put inside variables he/she need to change. +This approach covers most cases I have in my practice. Show your DevOp how to use `cfg` and put inside variables he/she needs to change. -Also `local.cfg` is ignored in `.gitignore` so you will not accidentally put your database passwords to public repository. +Also `local.cfg` is ignored in `.gitignore` so you will not accidentally put your database passwords to a public repository. ## `app.py` — cornerstone part of your application