aiohttp-devtools


Nameaiohttp-devtools JSON
Version 0.2 PyPI version JSON
home_pagehttps://github.com/samuelcolvin/aiohttp-devtools
SummaryDev tools for aiohttp
upload_time2017-02-19 17:53:27
maintainer
docs_urlNone
authorSamuel Colvin
requires_python
licenseMIT
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI
Coveralis test coverage
            aiohttp-devtools
================

|Build Status| |Coverage| |pypi| |license|

Dev tools for `aiohttp`_.

**aiohttp-devtools** provides a number of tools useful when developing applications with aiohttp and associated
libraries.

Installation
------------

Requires **python 3.5** or **python 3.6**.

.. code:: shell

    pip install aiohttp-devtools

Usage
-----

The ``aiohttp-devtools`` CLI (and it's shorter alias ``adev``) consist of three sub-commands:
`runserver`_, `serve`_ and `start`_.

runserver
~~~~~~~~~

Provides a simple local server for running your application while you're developing.

Usage is simply

.. code:: shell

    adev runserver <app-path>

``app-path`` can be a path to either a directory containing a recognized default file (``settings.y(a)ml``, ``app.py``
or ``main.py``) or to a specific file.

If a yaml file is found the "dev" dictionary in that file is used to populate settings for runserver
(the `start`_ command creates such a file),
if a python file is found it's run directly, the ``--app-factory`` option can be used to define which method is called,
if not supplied some default method names are tried.

``runserver`` has a few of useful features:

* **livereload** will reload resources in the browser as your code changes without having to hit refresh, see `livereload`_ for more details.
* **static files** are served separately from your main app (generally on ``8001`` while your app is on ``8000``) so you don't have to contaminate your application to serve static files you only need locally
* a **debug toolbar** is automatically enabled using `aiohttp debugtoolbar`_.

For more options see ``adev runserver --help``.

serve
~~~~~

Similar to `runserver`_ except just serves static files.

Usage is simply

.. code:: shell

    adev serve <path-to-directory-to-serve>

Like ``runserver`` you get nice live reloading and access logs. For more options see ``adev serve --help``.

start
~~~~~

Creates a new bare bones aiohttp app similar to django's "startproject".


Usage is simply

.. code:: shell

    adev start <path-to-directory-to-create-project-in>

You're then asked a bunch of questions about the the application you're about to create, you get to choose:

* **Template Engine**, options are

  - **jinja** views are rendered using Jinja2 templates via `aiohttp_jinja2`_.
  - **none** views are rendered directly.

* **Session**, options are

  - **secure** will implemented encrypted cookie sessions using `aiohttp_session`_.
  - **none** - session are not implemented

* **Database**, options are:

  - **pg-sqlalchemy** will use postgresql via `aiopg`_ and the `SqlAlchemy`_ ORM.
  - **none** will use no database, persistence in examples is achieved by simply writing to file. This is a quick way to get started but is obviously not suitable for production use!

* **Example**, the newly created app can include some basic functionality

  - **message board**: which demonstrates a little of aiohttp's usage. Messages can be added via posting to a form, are stored in the database and then displayed in a list, if available the session is used to pre-populate the user's name.
  - **none**: no example, just a single simple view is created.

For more options see ``adev start --help``, or just run ``adev start foobar`` and follow instructions.


Tutorial
--------

To demonstrate what adev can do, let's walk through creating a new application:

First let's create a clean python environment to work in and install aiohttp-devtools.

(it is assumed you've already got **python 3.5**, **pip** and **virtualenv** installed)

.. code:: shell

    mkdir my_new_app && cd my_new_app
    virtualenv -p `which python3.5` env
    . env/bin/activate
    pip install aiohttp-devtools


We're now ready to build our new application with `start`_, using the current directory ``.`` will put files where
we want them and will prompt adev to name the project ``my_new_app`` after the current directory.

We're going to explicitly choose no database here to make, this tutorial easier but you can remove that option
and choose to use a proper database if you like.

You can just hit return to choose the default for all the options.


.. code:: shell

    adev start . --database none

That's it, your app is now created. You might want to have a look through the local directory's file tree.

Before you can run your app you'll need to install the other requirements, luckily they've already been listed in
``./requirements.txt`` by `start`_, to install simply run

.. code:: shell

    pip install -r requirements.txt

(If you went off-piste and choose to use a database you'll need to edit ``settings.yml`` to configure connection settings,
then run ``make reset-database`` to create a database.)

You can then run your app with just:

.. code:: shell

    adev runserver .

`runserver`_ notices the ``settings.yml`` files and uses that to decide how to serve your app.

With that:

* your app should be being served at ``localhost:8000`` (you can go and play with it in a browser).
* Your static files are being served at ``localhost:8001``, adev has configured your app to know that so it should be rendering properly.
* any changes to your app's code (``.py`` files) should cause the server to reload, changes to any files (``.py`` as well as ``.jinja``, ``.js``, ``.css`` etc.) will cause livereload to prompt your browser to reload the required pages.

**That's it, go develop.**

.. |Build Status| image:: https://travis-ci.org/samuelcolvin/aiohttp-devtools.svg?branch=master
   :target: https://travis-ci.org/samuelcolvin/aiohttp-devtools
.. |Coverage| image:: https://codecov.io/gh/samuelcolvin/aiohttp-devtools/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/samuelcolvin/aiohttp-devtools
.. |pypi| image:: https://img.shields.io/pypi/v/aiohttp-devtools.svg
   :target: https://pypi.python.org/pypi/aiohttp-devtools
.. |license| image:: https://img.shields.io/pypi/l/aiohttp-devtools.svg
   :target: https://github.com/samuelcolvin/aiohttp-devtools
.. _livereload: https://github.com/livereload/livereload-js
.. _aiohttp: http://aiohttp.readthedocs.io/en/stable/
.. _aiohttp debugtoolbar: https://github.com/aio-libs/aiohttp_debugtoolbar
.. _aiohttp_jinja2: https://github.com/aio-libs/aiohttp_jinja2
.. _aiohttp_session: https://aiohttp-session.readthedocs.io/en/latest/
.. _aiopg: https://aiopg.readthedocs.io/en/latest/
.. _SqlAlchemy: http://www.sqlalchemy.org/
            

Raw data

            {
    "maintainer": "", 
    "docs_url": null, 
    "requires_python": "", 
    "maintainer_email": "", 
    "cheesecake_code_kwalitee_id": null, 
    "coveralis": true, 
    "keywords": "", 
    "upload_time": "2017-02-19 17:53:27", 
    "author": "Samuel Colvin", 
    "home_page": "https://github.com/samuelcolvin/aiohttp-devtools", 
    "github_user": "samuelcolvin", 
    "download_url": "https://pypi.python.org/packages/8c/2c/a82f6e82fac4851e18b94e6a224f0d801cb3d719c6d2f49615fa9908ec40/aiohttp-devtools-0.2.tar.gz", 
    "platform": "UNKNOWN", 
    "version": "0.2", 
    "cheesecake_documentation_id": null, 
    "description": "aiohttp-devtools\n================\n\n|Build Status| |Coverage| |pypi| |license|\n\nDev tools for `aiohttp`_.\n\n**aiohttp-devtools** provides a number of tools useful when developing applications with aiohttp and associated\nlibraries.\n\nInstallation\n------------\n\nRequires **python 3.5** or **python 3.6**.\n\n.. code:: shell\n\n    pip install aiohttp-devtools\n\nUsage\n-----\n\nThe ``aiohttp-devtools`` CLI (and it's shorter alias ``adev``) consist of three sub-commands:\n`runserver`_, `serve`_ and `start`_.\n\nrunserver\n~~~~~~~~~\n\nProvides a simple local server for running your application while you're developing.\n\nUsage is simply\n\n.. code:: shell\n\n    adev runserver <app-path>\n\n``app-path`` can be a path to either a directory containing a recognized default file (``settings.y(a)ml``, ``app.py``\nor ``main.py``) or to a specific file.\n\nIf a yaml file is found the \"dev\" dictionary in that file is used to populate settings for runserver\n(the `start`_ command creates such a file),\nif a python file is found it's run directly, the ``--app-factory`` option can be used to define which method is called,\nif not supplied some default method names are tried.\n\n``runserver`` has a few of useful features:\n\n* **livereload** will reload resources in the browser as your code changes without having to hit refresh, see `livereload`_ for more details.\n* **static files** are served separately from your main app (generally on ``8001`` while your app is on ``8000``) so you don't have to contaminate your application to serve static files you only need locally\n* a **debug toolbar** is automatically enabled using `aiohttp debugtoolbar`_.\n\nFor more options see ``adev runserver --help``.\n\nserve\n~~~~~\n\nSimilar to `runserver`_ except just serves static files.\n\nUsage is simply\n\n.. code:: shell\n\n    adev serve <path-to-directory-to-serve>\n\nLike ``runserver`` you get nice live reloading and access logs. For more options see ``adev serve --help``.\n\nstart\n~~~~~\n\nCreates a new bare bones aiohttp app similar to django's \"startproject\".\n\n\nUsage is simply\n\n.. code:: shell\n\n    adev start <path-to-directory-to-create-project-in>\n\nYou're then asked a bunch of questions about the the application you're about to create, you get to choose:\n\n* **Template Engine**, options are\n\n  - **jinja** views are rendered using Jinja2 templates via `aiohttp_jinja2`_.\n  - **none** views are rendered directly.\n\n* **Session**, options are\n\n  - **secure** will implemented encrypted cookie sessions using `aiohttp_session`_.\n  - **none** - session are not implemented\n\n* **Database**, options are:\n\n  - **pg-sqlalchemy** will use postgresql via `aiopg`_ and the `SqlAlchemy`_ ORM.\n  - **none** will use no database, persistence in examples is achieved by simply writing to file. This is a quick way to get started but is obviously not suitable for production use!\n\n* **Example**, the newly created app can include some basic functionality\n\n  - **message board**: which demonstrates a little of aiohttp's usage. Messages can be added via posting to a form, are stored in the database and then displayed in a list, if available the session is used to pre-populate the user's name.\n  - **none**: no example, just a single simple view is created.\n\nFor more options see ``adev start --help``, or just run ``adev start foobar`` and follow instructions.\n\n\nTutorial\n--------\n\nTo demonstrate what adev can do, let's walk through creating a new application:\n\nFirst let's create a clean python environment to work in and install aiohttp-devtools.\n\n(it is assumed you've already got **python 3.5**, **pip** and **virtualenv** installed)\n\n.. code:: shell\n\n    mkdir my_new_app && cd my_new_app\n    virtualenv -p `which python3.5` env\n    . env/bin/activate\n    pip install aiohttp-devtools\n\n\nWe're now ready to build our new application with `start`_, using the current directory ``.`` will put files where\nwe want them and will prompt adev to name the project ``my_new_app`` after the current directory.\n\nWe're going to explicitly choose no database here to make, this tutorial easier but you can remove that option\nand choose to use a proper database if you like.\n\nYou can just hit return to choose the default for all the options.\n\n\n.. code:: shell\n\n    adev start . --database none\n\nThat's it, your app is now created. You might want to have a look through the local directory's file tree.\n\nBefore you can run your app you'll need to install the other requirements, luckily they've already been listed in\n``./requirements.txt`` by `start`_, to install simply run\n\n.. code:: shell\n\n    pip install -r requirements.txt\n\n(If you went off-piste and choose to use a database you'll need to edit ``settings.yml`` to configure connection settings,\nthen run ``make reset-database`` to create a database.)\n\nYou can then run your app with just:\n\n.. code:: shell\n\n    adev runserver .\n\n`runserver`_ notices the ``settings.yml`` files and uses that to decide how to serve your app.\n\nWith that:\n\n* your app should be being served at ``localhost:8000`` (you can go and play with it in a browser).\n* Your static files are being served at ``localhost:8001``, adev has configured your app to know that so it should be rendering properly.\n* any changes to your app's code (``.py`` files) should cause the server to reload, changes to any files (``.py`` as well as ``.jinja``, ``.js``, ``.css`` etc.) will cause livereload to prompt your browser to reload the required pages.\n\n**That's it, go develop.**\n\n.. |Build Status| image:: https://travis-ci.org/samuelcolvin/aiohttp-devtools.svg?branch=master\n   :target: https://travis-ci.org/samuelcolvin/aiohttp-devtools\n.. |Coverage| image:: https://codecov.io/gh/samuelcolvin/aiohttp-devtools/branch/master/graph/badge.svg\n   :target: https://codecov.io/gh/samuelcolvin/aiohttp-devtools\n.. |pypi| image:: https://img.shields.io/pypi/v/aiohttp-devtools.svg\n   :target: https://pypi.python.org/pypi/aiohttp-devtools\n.. |license| image:: https://img.shields.io/pypi/l/aiohttp-devtools.svg\n   :target: https://github.com/samuelcolvin/aiohttp-devtools\n.. _livereload: https://github.com/livereload/livereload-js\n.. _aiohttp: http://aiohttp.readthedocs.io/en/stable/\n.. _aiohttp debugtoolbar: https://github.com/aio-libs/aiohttp_debugtoolbar\n.. _aiohttp_jinja2: https://github.com/aio-libs/aiohttp_jinja2\n.. _aiohttp_session: https://aiohttp-session.readthedocs.io/en/latest/\n.. _aiopg: https://aiopg.readthedocs.io/en/latest/\n.. _SqlAlchemy: http://www.sqlalchemy.org/", 
    "lcname": "aiohttp-devtools", 
    "bugtrack_url": null, 
    "github": true, 
    "name": "aiohttp-devtools", 
    "license": "MIT", 
    "travis_ci": true, 
    "github_project": "aiohttp-devtools", 
    "summary": "Dev tools for aiohttp", 
    "split_keywords": [], 
    "author_email": "s@muelcolvin.com", 
    "urls": [
        {
            "has_sig": false, 
            "upload_time": "2017-02-19T17:53:27", 
            "comment_text": "", 
            "python_version": "source", 
            "url": "https://pypi.python.org/packages/8c/2c/a82f6e82fac4851e18b94e6a224f0d801cb3d719c6d2f49615fa9908ec40/aiohttp-devtools-0.2.tar.gz", 
            "md5_digest": "5a0156364edbacdbd741d76bbef551f0", 
            "downloads": 0, 
            "filename": "aiohttp-devtools-0.2.tar.gz", 
            "packagetype": "sdist", 
            "path": "8c/2c/a82f6e82fac4851e18b94e6a224f0d801cb3d719c6d2f49615fa9908ec40/aiohttp-devtools-0.2.tar.gz", 
            "size": 35380
        }, 
        {
            "has_sig": false, 
            "upload_time": "2017-02-19T17:53:26", 
            "comment_text": "", 
            "python_version": "py35.py36", 
            "url": "https://pypi.python.org/packages/b6/6c/35fca550921a4e81347ce0808d48c1a84643b93d1a4c4bb76dcf238e7547/aiohttp_devtools-0.2-py35.py36-none-any.whl", 
            "md5_digest": "df31cee485be8b5eaaf0cdfd4da054a8", 
            "downloads": 0, 
            "filename": "aiohttp_devtools-0.2-py35.py36-none-any.whl", 
            "packagetype": "bdist_wheel", 
            "path": "b6/6c/35fca550921a4e81347ce0808d48c1a84643b93d1a4c4bb76dcf238e7547/aiohttp_devtools-0.2-py35.py36-none-any.whl", 
            "size": 48758
        }
    ], 
    "_id": null, 
    "cheesecake_installability_id": null
}