From aedd42545b77c52d1587e03983d4e4fb9056823a Mon Sep 17 00:00:00 2001 From: Chad Whitacre Date: Sat, 10 Sep 2016 15:44:58 -0400 Subject: [PATCH 01/10] Install dependencies under `make env` --- build.py | 1 + 1 file changed, 1 insertion(+) diff --git a/build.py b/build.py index 1bfa8eed..0a51ef17 100644 --- a/build.py +++ b/build.py @@ -80,6 +80,7 @@ def __env(envdir): def env(): """set up a base virtual environment""" _env() + _deps() def _deps(): From 39bd21fd5b81546c53483e7167723a8addb66967 Mon Sep 17 00:00:00 2001 From: Chad Whitacre Date: Sat, 10 Sep 2016 18:01:52 -0400 Subject: [PATCH 02/10] Update basic structure of docs --- aspen/__init__.py | 20 ++++ aspen/configuration/__init__.py | 8 ++ aspen/configuration/parse.py | 3 + aspen/exceptions.py | 5 + aspen/http/__init__.py | 13 +++ aspen/http/mapping.py | 4 + aspen/http/request.py | 2 + aspen/http/resource.py | 5 +- aspen/output.py | 6 ++ aspen/renderers.py | 5 + aspen/request_processor/__init__.py | 10 ++ aspen/request_processor/algorithm.py | 3 + aspen/request_processor/dispatcher.py | 3 + aspen/request_processor/typecasting.py | 3 + aspen/resources.py | 4 + aspen/simplates/__init__.py | 10 ++ aspen/simplates/json_.py | 4 + aspen/simplates/pagination.py | 4 + aspen/simplates/renderers/__init__.py | 9 ++ aspen/simplates/renderers/json_dump.py | 4 + aspen/simplates/renderers/jsonp_dump.py | 4 + aspen/simplates/renderers/stdlib_format.py | 4 + aspen/simplates/renderers/stdlib_percent.py | 4 + aspen/simplates/renderers/stdlib_template.py | 4 + aspen/simplates/simplate.py | 4 + aspen/testing.py | 5 + aspen/utils.py | 5 + docs/index.rst | 97 +------------------- 28 files changed, 157 insertions(+), 95 deletions(-) diff --git a/aspen/__init__.py b/aspen/__init__.py index 76780126..1d4c6cc3 100644 --- a/aspen/__init__.py +++ b/aspen/__init__.py @@ -1,3 +1,23 @@ +""" +######### + Aspen +######### + +Aspen is the way of working online! If you have any questions, just ask Chad +Whitacre, and I *know* it will be easy. Yes, I know it will be easy! + +.. automodule:: aspen.simplates +.. automodule:: aspen.http +.. automodule:: aspen.request_processor +.. automodule:: aspen.resources +.. automodule:: aspen.output +.. automodule:: aspen.renderers +.. automodule:: aspen.configuration +.. automodule:: aspen.exceptions +.. automodule:: aspen.testing +.. automodule:: aspen.utils + +""" from __future__ import absolute_import from __future__ import division from __future__ import print_function diff --git a/aspen/configuration/__init__.py b/aspen/configuration/__init__.py index ab66f1d2..3d4b4292 100644 --- a/aspen/configuration/__init__.py +++ b/aspen/configuration/__init__.py @@ -1,3 +1,11 @@ +""" +*************** + Configuration +*************** + +.. automodule:: aspen.configuration.parse + +""" from __future__ import absolute_import from __future__ import division from __future__ import print_function diff --git a/aspen/configuration/parse.py b/aspen/configuration/parse.py index 340a4062..bfdbb810 100644 --- a/aspen/configuration/parse.py +++ b/aspen/configuration/parse.py @@ -1,4 +1,7 @@ """ +Parsing and Validation +====================== + Define parser/validators for configuration system Each of these is guaranteed to be passed a unicode object as read from the diff --git a/aspen/exceptions.py b/aspen/exceptions.py index 38dec132..e2ae9bf1 100644 --- a/aspen/exceptions.py +++ b/aspen/exceptions.py @@ -1,3 +1,8 @@ +""" +************ + Exceptions +************ +""" from __future__ import absolute_import from __future__ import division from __future__ import print_function diff --git a/aspen/http/__init__.py b/aspen/http/__init__.py index e69de29b..10c9d61f 100644 --- a/aspen/http/__init__.py +++ b/aspen/http/__init__.py @@ -0,0 +1,13 @@ +""" +************ + HTTP Model +************ + +Aspen doesn't implement all of HTTP, only things related to filesystem +dispatch. + +.. automodule:: aspen.http.mapping +.. automodule:: aspen.http.request +.. automodule:: aspen.http.resource + +""" diff --git a/aspen/http/mapping.py b/aspen/http/mapping.py index c05213ca..49e40d24 100644 --- a/aspen/http/mapping.py +++ b/aspen/http/mapping.py @@ -1,3 +1,7 @@ +""" +Mapping +======= +""" from __future__ import absolute_import from __future__ import division from __future__ import print_function diff --git a/aspen/http/request.py b/aspen/http/request.py index 3ac79859..cea97221 100644 --- a/aspen/http/request.py +++ b/aspen/http/request.py @@ -1,4 +1,6 @@ """ +Request +======= """ from __future__ import absolute_import from __future__ import division diff --git a/aspen/http/resource.py b/aspen/http/resource.py index 1ae50b75..9f09a17f 100644 --- a/aspen/http/resource.py +++ b/aspen/http/resource.py @@ -1,4 +1,7 @@ - +""" +Resource +======== +""" import mimeparse from ..exceptions import NegotiationFailure diff --git a/aspen/output.py b/aspen/output.py index 64a938fa..291a119d 100644 --- a/aspen/output.py +++ b/aspen/output.py @@ -1,3 +1,9 @@ +""" +******** + Output +******** +""" + class Output(object): body = media_type = charset = None diff --git a/aspen/renderers.py b/aspen/renderers.py index 1ee2ccc3..a27c44a2 100644 --- a/aspen/renderers.py +++ b/aspen/renderers.py @@ -1,3 +1,8 @@ +""" +*********** + Renderers +*********** +""" # for backwards compatibility with aspen-renderer modules from .simplates.renderers import Factory, Renderer diff --git a/aspen/request_processor/__init__.py b/aspen/request_processor/__init__.py index 5bc36e8b..e61fde8d 100644 --- a/aspen/request_processor/__init__.py +++ b/aspen/request_processor/__init__.py @@ -1,3 +1,13 @@ +""" +******************* + Request Processor +******************* + +.. automodule:: aspen.request_processor.algorithm +.. automodule:: aspen.request_processor.dispatcher +.. automodule:: aspen.request_processor.typecasting + +""" from __future__ import absolute_import from __future__ import division from __future__ import print_function diff --git a/aspen/request_processor/algorithm.py b/aspen/request_processor/algorithm.py index c3f9140a..db006cd8 100644 --- a/aspen/request_processor/algorithm.py +++ b/aspen/request_processor/algorithm.py @@ -1,4 +1,7 @@ """ +Algorithm +========= + These functions comprise the request processing functionality of Aspen. The order of functions in this module defines Aspen algorithm for request diff --git a/aspen/request_processor/dispatcher.py b/aspen/request_processor/dispatcher.py index 7dde1ad5..4aa7175f 100644 --- a/aspen/request_processor/dispatcher.py +++ b/aspen/request_processor/dispatcher.py @@ -1,4 +1,7 @@ """ +Dispatcher +========== + Implement Aspen's filesystem dispatch algorithm. """ from __future__ import absolute_import diff --git a/aspen/request_processor/typecasting.py b/aspen/request_processor/typecasting.py index 00d531ef..8ed91f3b 100644 --- a/aspen/request_processor/typecasting.py +++ b/aspen/request_processor/typecasting.py @@ -1,4 +1,7 @@ """ +Typecasting +=========== + Pluggable typecasting of virtual path values """ from __future__ import absolute_import diff --git a/aspen/resources.py b/aspen/resources.py index 7489511c..dfde5e2e 100644 --- a/aspen/resources.py +++ b/aspen/resources.py @@ -1,4 +1,8 @@ """ +*********** + Resources +*********** + This is a registry of filesystem paths to objects representing HTTP resources. Use :py:func:`get` to use the cache, use :py:func:`load` to circumvent it. diff --git a/aspen/simplates/__init__.py b/aspen/simplates/__init__.py index e69de29b..6ee13c2a 100644 --- a/aspen/simplates/__init__.py +++ b/aspen/simplates/__init__.py @@ -0,0 +1,10 @@ +""" +*********** + Simplates +*********** + +.. automodule:: aspen.simplates.json_ +.. automodule:: aspen.simplates.pagination +.. automodule:: aspen.simplates.renderers + +""" diff --git a/aspen/simplates/json_.py b/aspen/simplates/json_.py index 351059e5..df67f43c 100644 --- a/aspen/simplates/json_.py +++ b/aspen/simplates/json_.py @@ -1,3 +1,7 @@ +""" +JSON +==== +""" from __future__ import absolute_import from __future__ import division from __future__ import print_function diff --git a/aspen/simplates/pagination.py b/aspen/simplates/pagination.py index 7d7fccfc..b748335e 100644 --- a/aspen/simplates/pagination.py +++ b/aspen/simplates/pagination.py @@ -1,3 +1,7 @@ +""" +Pagination +========== +""" from __future__ import absolute_import from __future__ import division from __future__ import print_function diff --git a/aspen/simplates/renderers/__init__.py b/aspen/simplates/renderers/__init__.py index 524bf8e6..71ab1070 100644 --- a/aspen/simplates/renderers/__init__.py +++ b/aspen/simplates/renderers/__init__.py @@ -1,4 +1,7 @@ """ +Renderers +========= + This module implements pluggable content rendering. Negotiated and rendered resources have content pages the bytes for which are @@ -68,6 +71,12 @@ class CheeseFactory(Factory): machinery is inadequate for some reason let's evolve the machinery so all renderers behave consistently for users. Thanks. +.. automodule:: aspen.simplates.renderers.jsonp_dump +.. automodule:: aspen.simplates.renderers.json_dump +.. automodule:: aspen.simplates.renderers.stdlib_format +.. automodule:: aspen.simplates.renderers.stdlib_percent +.. automodule:: aspen.simplates.renderers.stdlib_template + """ from __future__ import absolute_import from __future__ import division diff --git a/aspen/simplates/renderers/json_dump.py b/aspen/simplates/renderers/json_dump.py index 3fec21a5..27ed8f3c 100644 --- a/aspen/simplates/renderers/json_dump.py +++ b/aspen/simplates/renderers/json_dump.py @@ -1,3 +1,7 @@ +""" +json_dump +--------- +""" from __future__ import absolute_import from __future__ import division from __future__ import print_function diff --git a/aspen/simplates/renderers/jsonp_dump.py b/aspen/simplates/renderers/jsonp_dump.py index 5ec64f3d..86cae845 100644 --- a/aspen/simplates/renderers/jsonp_dump.py +++ b/aspen/simplates/renderers/jsonp_dump.py @@ -1,3 +1,7 @@ +""" +jsonp_dump +---------- +""" from __future__ import absolute_import from __future__ import division from __future__ import print_function diff --git a/aspen/simplates/renderers/stdlib_format.py b/aspen/simplates/renderers/stdlib_format.py index 3aff9c27..62aeea8b 100644 --- a/aspen/simplates/renderers/stdlib_format.py +++ b/aspen/simplates/renderers/stdlib_format.py @@ -1,3 +1,7 @@ +""" +stdlib_format +------------- +""" from __future__ import absolute_import from __future__ import division from __future__ import print_function diff --git a/aspen/simplates/renderers/stdlib_percent.py b/aspen/simplates/renderers/stdlib_percent.py index 847be9cf..107c4348 100644 --- a/aspen/simplates/renderers/stdlib_percent.py +++ b/aspen/simplates/renderers/stdlib_percent.py @@ -1,3 +1,7 @@ +""" +stdlib_percent +-------------- +""" from __future__ import absolute_import from __future__ import division from __future__ import print_function diff --git a/aspen/simplates/renderers/stdlib_template.py b/aspen/simplates/renderers/stdlib_template.py index ce053264..92799778 100644 --- a/aspen/simplates/renderers/stdlib_template.py +++ b/aspen/simplates/renderers/stdlib_template.py @@ -1,3 +1,7 @@ +""" +stdlib_template +--------------- +""" from __future__ import absolute_import from __future__ import division from __future__ import print_function diff --git a/aspen/simplates/simplate.py b/aspen/simplates/simplate.py index 483cce63..85d28631 100644 --- a/aspen/simplates/simplate.py +++ b/aspen/simplates/simplate.py @@ -1,3 +1,7 @@ +""" +Simplate +======== +""" from __future__ import absolute_import from __future__ import division from __future__ import print_function diff --git a/aspen/testing.py b/aspen/testing.py index e1c919f5..8ae07840 100644 --- a/aspen/testing.py +++ b/aspen/testing.py @@ -1,3 +1,8 @@ +""" +********* + Testing +********* +""" from __future__ import absolute_import from __future__ import division from __future__ import print_function diff --git a/aspen/utils.py b/aspen/utils.py index e4e2c42b..0ee692ba 100644 --- a/aspen/utils.py +++ b/aspen/utils.py @@ -1,3 +1,8 @@ +""" +******* + Utils +******* +""" from __future__ import absolute_import from __future__ import division from __future__ import print_function diff --git a/docs/index.rst b/docs/index.rst index fc7d4aba..8eea7642 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,95 +1,4 @@ -************ -aspen module -************ - .. automodule:: aspen - -configuration -============= - -.. automodule:: aspen.configuration - -parse ------ - -.. automodule:: aspen.configuration.parse - -exceptions -========== - -.. automodule:: aspen.exceptions - -http -==== - -.. automodule:: aspen.http - -mapping -------- - -.. automodule:: aspen.http.mapping - -request -------- - -.. automodule:: aspen.http.request - -request_processor -================= - -.. automodule:: aspen.request_processor - -algorithm ---------- - -.. automodule:: aspen.request_processor.algorithm - -dispatcher ----------- - -.. automodule:: aspen.request_processor.dispatcher - -typecasting ------------ - -.. automodule:: aspen.request_processor.typecasting - -resources -========= - -.. automodule:: aspen.resources - -simplates -========= - -.. automodule:: aspen.simplates - -json_ ------ - -.. automodule:: aspen.simplates.json_ - -pagination ----------- - -.. automodule:: aspen.simplates.pagination - -simplate --------- - -.. automodule:: aspen.simplates.simplate - -renderers ---------- - -.. automodule:: aspen.simplates.renderers - -testing -======= - -.. automodule:: aspen.testing - -utils -===== - -.. automodule:: aspen.utils + :members: + :member-order: bysource + :special-members: From 62743b28c445bc1c78caa9e51156093d39dbe54c Mon Sep 17 00:00:00 2001 From: Chad Whitacre Date: Sat, 10 Sep 2016 20:59:26 -0400 Subject: [PATCH 03/10] Nest library docs under "Reference" --- aspen/__init__.py | 67 +++++++++++++++++++- aspen/configuration/__init__.py | 8 ++- aspen/configuration/parse.py | 5 +- aspen/exceptions.py | 7 +- aspen/http/__init__.py | 5 +- aspen/http/mapping.py | 6 +- aspen/http/request.py | 6 +- aspen/http/resource.py | 6 +- aspen/output.py | 7 +- aspen/renderers.py | 6 -- aspen/request_processor/__init__.py | 7 +- aspen/request_processor/algorithm.py | 4 +- aspen/request_processor/dispatcher.py | 4 +- aspen/request_processor/typecasting.py | 4 +- aspen/resources.py | 5 +- aspen/simplates/__init__.py | 7 +- aspen/simplates/json_.py | 4 +- aspen/simplates/pagination.py | 4 +- aspen/simplates/renderers/__init__.py | 4 +- aspen/simplates/renderers/json_dump.py | 4 +- aspen/simplates/renderers/jsonp_dump.py | 4 +- aspen/simplates/renderers/stdlib_format.py | 4 +- aspen/simplates/renderers/stdlib_percent.py | 4 +- aspen/simplates/renderers/stdlib_template.py | 4 +- aspen/simplates/simplate.py | 4 +- aspen/testing.py | 5 +- aspen/utils.py | 5 +- 27 files changed, 132 insertions(+), 68 deletions(-) diff --git a/aspen/__init__.py b/aspen/__init__.py index 1d4c6cc3..049c5362 100644 --- a/aspen/__init__.py +++ b/aspen/__init__.py @@ -3,15 +3,76 @@ Aspen ######### -Aspen is the way of working online! If you have any questions, just ask Chad -Whitacre, and I *know* it will be easy. Yes, I know it will be easy! +Aspen is a filesystem dispatch library for Python web frameworks. Instead of +regular expressions, decorators, or object traversal, Aspen dispatches HTTP +requests based on the natural symmetry of URL paths and filesystem paths. In +the `immortal words`_ of Jeff Lindsay, "so like. a web server." Exactly! ;-) + +.. _immortal words: https://twitter.com/progrium/status/773694289033383937 + +This is the documentation for the development version of the core Aspen +library, describing its filesystem dispatch behavior regardless of the web +framework you're using it with. For instructions on configuring Aspen with a +specific web framework, see the docs for `django-aspen`_, `Flask-Aspen`_, or +`Pando`_. See the `project homepage`_ for an overview. + +.. _django-aspen: http://django.aspen.io/ +.. _Flask-aspen: http://flask.aspen.io/ +.. _Pando: http://pando.aspen.io/ +.. _project homepage: http://aspen.io/ + +This version of Aspen has been tested with Python 2.7, 3.4, and 3.5, on both +Ubuntu and Windows. + + +************** + Installation +************** + +Aspen is available on `GitHub`_ and on `PyPI`_:: + + $ pip install aspen + +.. _GitHub: https://github.com/AspenWeb/aspen.py +.. _PyPI: https://pypi.python.org/pypi/aspen + + +******* + Legal +******* + +Aspen is distributed under the `MIT license`_. + +.. _MIT license: https://github.com/AspenWeb/aspen.py/blob/master/COPYRIGHT + + +********** + See Also +********** + +The `Keystone`_ web framework was inspired by Aspen. + +.. _Keystone: http://keystone.readthedocs.org/ + + +********** + Tutorial +********** + +Foo bar + + +*********** + Reference +*********** + +No? .. automodule:: aspen.simplates .. automodule:: aspen.http .. automodule:: aspen.request_processor .. automodule:: aspen.resources .. automodule:: aspen.output -.. automodule:: aspen.renderers .. automodule:: aspen.configuration .. automodule:: aspen.exceptions .. automodule:: aspen.testing diff --git a/aspen/configuration/__init__.py b/aspen/configuration/__init__.py index 3d4b4292..e2f55858 100644 --- a/aspen/configuration/__init__.py +++ b/aspen/configuration/__init__.py @@ -1,7 +1,9 @@ """ -*************** - Configuration -*************** + +:mod:`configuration` +==================== + +Configuration. .. automodule:: aspen.configuration.parse diff --git a/aspen/configuration/parse.py b/aspen/configuration/parse.py index bfdbb810..b28a8333 100644 --- a/aspen/configuration/parse.py +++ b/aspen/configuration/parse.py @@ -1,6 +1,7 @@ """ -Parsing and Validation -====================== + +:mod:`parse` +============ Define parser/validators for configuration system diff --git a/aspen/exceptions.py b/aspen/exceptions.py index e2ae9bf1..dacbef8f 100644 --- a/aspen/exceptions.py +++ b/aspen/exceptions.py @@ -1,7 +1,8 @@ """ -************ - Exceptions -************ +:mod:`exceptions` +================= + +Exceptions. """ from __future__ import absolute_import from __future__ import division diff --git a/aspen/http/__init__.py b/aspen/http/__init__.py index 10c9d61f..0c84e1be 100644 --- a/aspen/http/__init__.py +++ b/aspen/http/__init__.py @@ -1,7 +1,6 @@ """ -************ - HTTP Model -************ +:mod:`http` +=========== Aspen doesn't implement all of HTTP, only things related to filesystem dispatch. diff --git a/aspen/http/mapping.py b/aspen/http/mapping.py index 49e40d24..cfa104ba 100644 --- a/aspen/http/mapping.py +++ b/aspen/http/mapping.py @@ -1,6 +1,8 @@ """ -Mapping -======= +:mod:`mapping` +-------------- + +Mapping. """ from __future__ import absolute_import from __future__ import division diff --git a/aspen/http/request.py b/aspen/http/request.py index cea97221..0e095163 100644 --- a/aspen/http/request.py +++ b/aspen/http/request.py @@ -1,6 +1,8 @@ """ -Request -======= +:mod:`request` +-------------- + +Request. """ from __future__ import absolute_import from __future__ import division diff --git a/aspen/http/resource.py b/aspen/http/resource.py index 9f09a17f..0416aba1 100644 --- a/aspen/http/resource.py +++ b/aspen/http/resource.py @@ -1,6 +1,8 @@ """ -Resource -======== +:mod:`resource` +--------------- + +Resource. """ import mimeparse diff --git a/aspen/output.py b/aspen/output.py index 291a119d..d94d72d5 100644 --- a/aspen/output.py +++ b/aspen/output.py @@ -1,7 +1,8 @@ """ -******** - Output -******** +:mod:`output` +============= + +Output. """ class Output(object): diff --git a/aspen/renderers.py b/aspen/renderers.py index a27c44a2..a040cd98 100644 --- a/aspen/renderers.py +++ b/aspen/renderers.py @@ -1,9 +1,3 @@ -""" -*********** - Renderers -*********** -""" - # for backwards compatibility with aspen-renderer modules from .simplates.renderers import Factory, Renderer diff --git a/aspen/request_processor/__init__.py b/aspen/request_processor/__init__.py index e61fde8d..66f4012b 100644 --- a/aspen/request_processor/__init__.py +++ b/aspen/request_processor/__init__.py @@ -1,7 +1,8 @@ """ -******************* - Request Processor -******************* +:mod:`request_processor` +======================== + +Request processor. .. automodule:: aspen.request_processor.algorithm .. automodule:: aspen.request_processor.dispatcher diff --git a/aspen/request_processor/algorithm.py b/aspen/request_processor/algorithm.py index db006cd8..6ac512d0 100644 --- a/aspen/request_processor/algorithm.py +++ b/aspen/request_processor/algorithm.py @@ -1,6 +1,6 @@ """ -Algorithm -========= +:mod:`algorithm` +---------------- These functions comprise the request processing functionality of Aspen. diff --git a/aspen/request_processor/dispatcher.py b/aspen/request_processor/dispatcher.py index 4aa7175f..34f9d2f7 100644 --- a/aspen/request_processor/dispatcher.py +++ b/aspen/request_processor/dispatcher.py @@ -1,6 +1,6 @@ """ -Dispatcher -========== +:mod:`dispatcher` +----------------- Implement Aspen's filesystem dispatch algorithm. """ diff --git a/aspen/request_processor/typecasting.py b/aspen/request_processor/typecasting.py index 8ed91f3b..9f3c8671 100644 --- a/aspen/request_processor/typecasting.py +++ b/aspen/request_processor/typecasting.py @@ -1,6 +1,6 @@ """ -Typecasting -=========== +:mod:`typecasting` +------------------ Pluggable typecasting of virtual path values """ diff --git a/aspen/resources.py b/aspen/resources.py index dfde5e2e..7e800931 100644 --- a/aspen/resources.py +++ b/aspen/resources.py @@ -1,7 +1,6 @@ """ -*********** - Resources -*********** +:mod:`resources` +================ This is a registry of filesystem paths to objects representing HTTP resources. diff --git a/aspen/simplates/__init__.py b/aspen/simplates/__init__.py index 6ee13c2a..ae2dcf95 100644 --- a/aspen/simplates/__init__.py +++ b/aspen/simplates/__init__.py @@ -1,7 +1,8 @@ """ -*********** - Simplates -*********** +:mod:`simplates` +================ + +Yes. .. automodule:: aspen.simplates.json_ .. automodule:: aspen.simplates.pagination diff --git a/aspen/simplates/json_.py b/aspen/simplates/json_.py index df67f43c..32dbaaae 100644 --- a/aspen/simplates/json_.py +++ b/aspen/simplates/json_.py @@ -1,6 +1,6 @@ """ -JSON -==== +:mod:`json_` +------------ """ from __future__ import absolute_import from __future__ import division diff --git a/aspen/simplates/pagination.py b/aspen/simplates/pagination.py index b748335e..890f81c8 100644 --- a/aspen/simplates/pagination.py +++ b/aspen/simplates/pagination.py @@ -1,6 +1,6 @@ """ -Pagination -========== +:mod:`pagination` +----------------- """ from __future__ import absolute_import from __future__ import division diff --git a/aspen/simplates/renderers/__init__.py b/aspen/simplates/renderers/__init__.py index 71ab1070..dd11e988 100644 --- a/aspen/simplates/renderers/__init__.py +++ b/aspen/simplates/renderers/__init__.py @@ -1,6 +1,6 @@ """ -Renderers -========= +:mod:`renderers` +---------------- This module implements pluggable content rendering. diff --git a/aspen/simplates/renderers/json_dump.py b/aspen/simplates/renderers/json_dump.py index 27ed8f3c..03657e6f 100644 --- a/aspen/simplates/renderers/json_dump.py +++ b/aspen/simplates/renderers/json_dump.py @@ -1,6 +1,6 @@ """ -json_dump ---------- +:mod:`json_dump` +^^^^^^^^^^^^^^^^ """ from __future__ import absolute_import from __future__ import division diff --git a/aspen/simplates/renderers/jsonp_dump.py b/aspen/simplates/renderers/jsonp_dump.py index 86cae845..4c601a54 100644 --- a/aspen/simplates/renderers/jsonp_dump.py +++ b/aspen/simplates/renderers/jsonp_dump.py @@ -1,6 +1,6 @@ """ -jsonp_dump ----------- +:mod:`jsonp_dump` +^^^^^^^^^^^^^^^^^^ """ from __future__ import absolute_import from __future__ import division diff --git a/aspen/simplates/renderers/stdlib_format.py b/aspen/simplates/renderers/stdlib_format.py index 62aeea8b..15f4138d 100644 --- a/aspen/simplates/renderers/stdlib_format.py +++ b/aspen/simplates/renderers/stdlib_format.py @@ -1,6 +1,6 @@ """ -stdlib_format -------------- +:mod:`stdlib_format` +^^^^^^^^^^^^^^^^^^^^ """ from __future__ import absolute_import from __future__ import division diff --git a/aspen/simplates/renderers/stdlib_percent.py b/aspen/simplates/renderers/stdlib_percent.py index 107c4348..2a02a97d 100644 --- a/aspen/simplates/renderers/stdlib_percent.py +++ b/aspen/simplates/renderers/stdlib_percent.py @@ -1,6 +1,6 @@ """ -stdlib_percent --------------- +:mod:`stdlib_percent` +^^^^^^^^^^^^^^^^^^^^^ """ from __future__ import absolute_import from __future__ import division diff --git a/aspen/simplates/renderers/stdlib_template.py b/aspen/simplates/renderers/stdlib_template.py index 92799778..aa830ed7 100644 --- a/aspen/simplates/renderers/stdlib_template.py +++ b/aspen/simplates/renderers/stdlib_template.py @@ -1,6 +1,6 @@ """ -stdlib_template ---------------- +:mod:`stdlib_template` +^^^^^^^^^^^^^^^^^^^^^^ """ from __future__ import absolute_import from __future__ import division diff --git a/aspen/simplates/simplate.py b/aspen/simplates/simplate.py index 85d28631..0d1f3f4d 100644 --- a/aspen/simplates/simplate.py +++ b/aspen/simplates/simplate.py @@ -1,6 +1,6 @@ """ -Simplate -======== +:mod:`simplate` +--------------- """ from __future__ import absolute_import from __future__ import division diff --git a/aspen/testing.py b/aspen/testing.py index 8ae07840..314bbdfc 100644 --- a/aspen/testing.py +++ b/aspen/testing.py @@ -1,7 +1,6 @@ """ -********* - Testing -********* +:mod:`testing` +============== """ from __future__ import absolute_import from __future__ import division diff --git a/aspen/utils.py b/aspen/utils.py index 0ee692ba..2fdee81c 100644 --- a/aspen/utils.py +++ b/aspen/utils.py @@ -1,7 +1,6 @@ """ -******* - Utils -******* +:mod:`utils` +============ """ from __future__ import absolute_import from __future__ import division From 98d0a6f432352b221e041087b08ca91e6aa9e6ec Mon Sep 17 00:00:00 2001 From: Chad Whitacre Date: Sun, 11 Sep 2016 21:56:45 -0400 Subject: [PATCH 04/10] Replace placeholders with minimal sentences --- aspen/__init__.py | 15 ++++--------- aspen/http/mapping.py | 12 +++++----- aspen/http/request.py | 2 +- aspen/http/resource.py | 2 +- aspen/output.py | 3 ++- aspen/request_processor/__init__.py | 5 ++++- aspen/request_processor/typecasting.py | 3 ++- aspen/simplates/__init__.py | 31 +++++++++++++++++++++++--- aspen/testing.py | 3 +++ aspen/utils.py | 4 ++++ 10 files changed, 55 insertions(+), 25 deletions(-) diff --git a/aspen/__init__.py b/aspen/__init__.py index 049c5362..df98148a 100644 --- a/aspen/__init__.py +++ b/aspen/__init__.py @@ -4,9 +4,9 @@ ######### Aspen is a filesystem dispatch library for Python web frameworks. Instead of -regular expressions, decorators, or object traversal, Aspen dispatches HTTP -requests based on the natural symmetry of URL paths and filesystem paths. In -the `immortal words`_ of Jeff Lindsay, "so like. a web server." Exactly! ;-) +using regular expressions, decorators, or object traversal, Aspen dispatches +HTTP requests based on the natural symmetry of URL paths and filesystem paths. +In the `immortal words`_ of Jeff Lindsay, "so like. a web server." Exactly! ;-) .. _immortal words: https://twitter.com/progrium/status/773694289033383937 @@ -55,18 +55,11 @@ .. _Keystone: http://keystone.readthedocs.org/ -********** - Tutorial -********** - -Foo bar - - *********** Reference *********** -No? +This is the API reference for the Aspen library. .. automodule:: aspen.simplates .. automodule:: aspen.http diff --git a/aspen/http/mapping.py b/aspen/http/mapping.py index cfa104ba..cf90bd3c 100644 --- a/aspen/http/mapping.py +++ b/aspen/http/mapping.py @@ -2,7 +2,8 @@ :mod:`mapping` -------------- -Mapping. +This module implements a class to represent HTTP mappings. + """ from __future__ import absolute_import from __future__ import division @@ -10,20 +11,19 @@ from __future__ import unicode_literals - NO_DEFAULT = object() class Mapping(dict): - """Base class for HTTP mappings: Path, Querystring, Headers, Cookie, Body. + """Base class for HTTP mappings. Mappings in HTTP differ from Python dictionaries in that they may have one or more values. This dictionary subclass maintains a list of values for - each key. However, access semantics are asymetric: subscript assignment - clobbers to the list, while subscript access returns the last item. Think + each key. However, access semantics are asymmetric: subscript assignment + clobbers to list, while subscript access returns the last item. Think about it. - WARNING: this isn't thread-safe + .. warning:: This isn't thread-safe. """ diff --git a/aspen/http/request.py b/aspen/http/request.py index 0e095163..1b1bab06 100644 --- a/aspen/http/request.py +++ b/aspen/http/request.py @@ -2,7 +2,7 @@ :mod:`request` -------------- -Request. +Aspen models the path and querystring parts of an HTTP request message. """ from __future__ import absolute_import from __future__ import division diff --git a/aspen/http/resource.py b/aspen/http/resource.py index 0416aba1..41de6043 100644 --- a/aspen/http/resource.py +++ b/aspen/http/resource.py @@ -2,7 +2,7 @@ :mod:`resource` --------------- -Resource. +This module implements classes for modeling static and dynamic HTTP resources. """ import mimeparse diff --git a/aspen/output.py b/aspen/output.py index d94d72d5..338f6fea 100644 --- a/aspen/output.py +++ b/aspen/output.py @@ -2,7 +2,8 @@ :mod:`output` ============= -Output. +Implement a class for capturing request processing output. + """ class Output(object): diff --git a/aspen/request_processor/__init__.py b/aspen/request_processor/__init__.py index 66f4012b..720af470 100644 --- a/aspen/request_processor/__init__.py +++ b/aspen/request_processor/__init__.py @@ -2,7 +2,10 @@ :mod:`request_processor` ======================== -Request processor. +The request processor dispatches requests to the filesystem (typecasting URL +path variables), loads the resource from the filesystem, and then renders and +encodes the resource. This algorithm is defined in the :mod:`algorithm` module, +with dispatching and typecasting in additional modules. .. automodule:: aspen.request_processor.algorithm .. automodule:: aspen.request_processor.dispatcher diff --git a/aspen/request_processor/typecasting.py b/aspen/request_processor/typecasting.py index 9f3c8671..97e14e1a 100644 --- a/aspen/request_processor/typecasting.py +++ b/aspen/request_processor/typecasting.py @@ -2,7 +2,8 @@ :mod:`typecasting` ------------------ -Pluggable typecasting of virtual path values +This module implements pluggable typecasting of URL path variables. + """ from __future__ import absolute_import from __future__ import division diff --git a/aspen/simplates/__init__.py b/aspen/simplates/__init__.py index ae2dcf95..1451b5c8 100644 --- a/aspen/simplates/__init__.py +++ b/aspen/simplates/__init__.py @@ -2,10 +2,35 @@ :mod:`simplates` ================ -Yes. +The simplates module implements Aspen's file format, simplates (*.spt). +Simplates combine request processing logic (think: Rails controller, or Django +view) with template code in one file. Here's an example:: + + # Python syntax. Runs once on startup. + import random + + [----] + # Python syntax. Runs once per request.. + program = request.qs['program'] + excitement = '!' * random.randint(1, 10) + + # One of the following is used on each request, based on content type + # negotiation. The syntax depends on the renderer. + + [----] text/html via jinja2 +

Greetings, {{ program }}{{ excitement }}

+ + [----] text/plain via stdlib_format + Greetings, {program}{excitement} + + [----] application/json via json_dump + { "program": program + , "excitement": excitement + } + -.. automodule:: aspen.simplates.json_ -.. automodule:: aspen.simplates.pagination .. automodule:: aspen.simplates.renderers +.. automodule:: aspen.simplates.pagination +.. automodule:: aspen.simplates.json_ """ diff --git a/aspen/testing.py b/aspen/testing.py index 314bbdfc..8f7b3761 100644 --- a/aspen/testing.py +++ b/aspen/testing.py @@ -1,6 +1,9 @@ """ :mod:`testing` ============== + +This module provides helpers for testing applications that use Aspen. + """ from __future__ import absolute_import from __future__ import division diff --git a/aspen/utils.py b/aspen/utils.py index 2fdee81c..0e909895 100644 --- a/aspen/utils.py +++ b/aspen/utils.py @@ -1,6 +1,10 @@ """ :mod:`utils` ============ + +This module collects a few random bits that should be placed somewhere that +makes more sense. + """ from __future__ import absolute_import from __future__ import division From a520549a1ee44b5e2945d2a157a97c9d871a344b Mon Sep 17 00:00:00 2001 From: Changaco Date: Mon, 12 Sep 2016 14:45:20 +0200 Subject: [PATCH 05/10] clean up sphinx config --- docs/conf.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index a08f9f42..6541199a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -32,7 +32,7 @@ # General information about the project. project = u'Aspen' -copyright = u'2016, Chad Whitacre, Paul Jimenez, and others' +copyright = u'2016, Chad Whitacre et al.' # The full version, including alpha/beta/rc tags. release = open('../version.txt').read().strip() @@ -69,7 +69,7 @@ # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ ('index', 'Aspen.tex', u'Aspen Documentation', - u'Chad Whitacre, Paul Jimenez, and others', 'manual'), + u'Chad Whitacre et al.', 'manual'), ] @@ -79,7 +79,7 @@ # (source start file, name, description, authors, manual section). man_pages = [ ('index', 'aspen', u'Aspen Documentation', - [u'Chad Whitacre, Paul Jimenez, and others'], 1) + [u'Chad Whitacre et al.'], 1) ] @@ -90,7 +90,7 @@ # dir menu entry, description, category) texinfo_documents = [ ('index', 'Aspen', u'Aspen Documentation', - u'Chad Whitacre, Paul Jimenez, and others', 'Aspen', + u'Chad Whitacre et al.', 'Aspen', 'A filesystem router for Python web frameworks.', 'Miscellaneous'), ] From 00a06ee49d89c2ddf57f8488edb48e2083287907 Mon Sep 17 00:00:00 2001 From: Changaco Date: Mon, 12 Sep 2016 16:24:06 +0200 Subject: [PATCH 06/10] switch to requirements.txt files external tools like requirements files, including readthedocs --- build.py | 22 ++-------------------- requirements.txt | 6 ++++++ requirements_tests.txt | 6 ++++++ setup.py | 6 ++---- 4 files changed, 16 insertions(+), 24 deletions(-) create mode 100644 requirements.txt create mode 100644 requirements_tests.txt diff --git a/build.py b/build.py index 0a51ef17..348d1144 100644 --- a/build.py +++ b/build.py @@ -9,24 +9,6 @@ # Core Executables # ================ -ASPEN_DEPS = [ - 'python-mimeparse>=0.1.4', - 'first>=2.0.1', - 'algorithm>=1.0.0', - 'filesystem_tree>=1.0.1', - 'dependency_injection>=1.1.0', - 'six', - ] - -TEST_DEPS = [ - 'coverage>=3.7.1', - 'cov-core>=1.7', - 'py>=1.4.20', - 'pyflakes', - 'pytest>=2.5.2', - 'pytest-cov>=1.6', - ] - ENV_ARGS = [ '-m', 'virtualenv', '--prompt=[aspen]', @@ -84,12 +66,12 @@ def env(): def _deps(): - shell('pip', 'install', *ASPEN_DEPS, ignore_status=False) + shell('pip', 'install', '-r', 'requirements.txt', ignore_status=False) def _test_deps(): _deps() - shell('pip', 'install', *TEST_DEPS, ignore_status=False) + shell('pip', 'install', '-r', 'requirements_tests.txt', ignore_status=False) def _dev(envdir='env'): diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..76451221 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,6 @@ +python-mimeparse>=0.1.4 +first>=2.0.1 +algorithm>=1.0.0 +filesystem_tree>=1.0.1 +dependency_injection>=1.1.0 +six diff --git a/requirements_tests.txt b/requirements_tests.txt new file mode 100644 index 00000000..d1290c25 --- /dev/null +++ b/requirements_tests.txt @@ -0,0 +1,6 @@ +coverage>=3.7.1 +cov-core>=1.7 +py>=1.4.20 +pyflakes +pytest>=2.5.2 +pytest-cov>=1.6 diff --git a/setup.py b/setup.py index f7b9a560..21ff72e7 100644 --- a/setup.py +++ b/setup.py @@ -6,8 +6,6 @@ from setuptools import find_packages, setup -from build import ASPEN_DEPS, TEST_DEPS - version = open('version.txt').read() @@ -32,6 +30,6 @@ , version = version , zip_safe = False , package_data = {'aspen': ['request_processor/mime.types']} - , install_requires = ASPEN_DEPS - , tests_require = TEST_DEPS + , install_requires = open('requirements.txt').read() + , tests_require = open('requirements_tests.txt').read() ) From d9703c8c98a181585db1a56a48df9bd54163d860 Mon Sep 17 00:00:00 2001 From: Changaco Date: Tue, 13 Sep 2016 11:50:46 +0200 Subject: [PATCH 07/10] prune old dependency from `requirements.txt` --- requirements.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 76451221..cc93ec9c 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,4 @@ python-mimeparse>=0.1.4 -first>=2.0.1 algorithm>=1.0.0 filesystem_tree>=1.0.1 dependency_injection>=1.1.0 From 6289310b36f92689a55af8829471b664b37e7011 Mon Sep 17 00:00:00 2001 From: Changaco Date: Mon, 12 Sep 2016 17:09:35 +0200 Subject: [PATCH 08/10] fix sphinx targets in `build.py` --- build.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build.py b/build.py index 348d1144..83f03d9c 100644 --- a/build.py +++ b/build.py @@ -62,7 +62,6 @@ def __env(envdir): def env(): """set up a base virtual environment""" _env() - _deps() def _deps(): @@ -105,6 +104,7 @@ def clean(): def _sphinx_cmd(packages, cmd): envdir = _env() + _deps() run('pip', 'install', *packages) builddir = 'docs/_build' run('mkdir', '-p', builddir) From 7a410e87b5c8cf06c27d616b8d01d0d130e4f45f Mon Sep 17 00:00:00 2001 From: Changaco Date: Mon, 12 Sep 2016 18:34:25 +0200 Subject: [PATCH 09/10] use RtD sphinx theme --- build.py | 9 ++++----- docs/conf.py | 6 +++--- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/build.py b/build.py index 83f03d9c..f139b9bb 100644 --- a/build.py +++ b/build.py @@ -102,10 +102,10 @@ def clean(): # Docs # ==== -def _sphinx_cmd(packages, cmd): +def _sphinx_cmd(cmd, extra_pkgs=[]): envdir = _env() _deps() - run('pip', 'install', *packages) + run('pip', 'install', *(['sphinx', 'sphinx-rtd-theme'] + extra_pkgs)) builddir = 'docs/_build' run('mkdir', '-p', builddir) args = ['-b', 'html', '-d', builddir + '/doctrees', 'docs', builddir + '/html'] @@ -113,16 +113,15 @@ def _sphinx_cmd(packages, cmd): def sphinx(): """build sphinx documents""" - _sphinx_cmd(['sphinx'], "sphinx-build") + _sphinx_cmd("sphinx-build") def autosphinx(): """run sphinx-autobuild""" - _sphinx_cmd(['sphinx', 'sphinx-autobuild'], "sphinx-autobuild") + _sphinx_cmd("sphinx-autobuild", extra_pkgs=['sphinx-autobuild']) def clean_sphinx(): """clean sphinx artifacts""" shell('rm', '-rf', 'docs/_build') - shell('rm', '-rf', 'denv') # Testing diff --git a/docs/conf.py b/docs/conf.py index 6541199a..78435940 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -55,9 +55,9 @@ # -- Options for HTML output --------------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = 'default' +import sphinx_rtd_theme +html_theme = "sphinx_rtd_theme" +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # Output file base name for HTML help builder. htmlhelp_basename = 'Aspendoc' From 24a78a0ad50611ed32c53491a6d9996514a1aef6 Mon Sep 17 00:00:00 2001 From: Changaco Date: Mon, 12 Sep 2016 18:35:55 +0200 Subject: [PATCH 10/10] only install tox when necessary --- build.py | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/build.py b/build.py index f139b9bb..58bd60cf 100644 --- a/build.py +++ b/build.py @@ -34,11 +34,6 @@ def _env(envdir='env'): # extend the PATH path = os.path.join(d, 'Scripts' if os.name == "nt" else 'bin') os.environ['PATH'] = path + os.pathsep + os.environ.get('PATH', '') - # install tox if it isn't there - try: - shell('pip', 'show', 'tox') - except ExecutionError: - run('pip', 'install', 'tox') return d @@ -64,6 +59,14 @@ def env(): _env() +def _install_tox(): + # install tox if it isn't there + try: + shell('pip', 'show', 'tox') + except ExecutionError: + run('pip', 'install', 'tox') + + def _deps(): shell('pip', 'install', '-r', 'requirements.txt', ignore_status=False) @@ -75,6 +78,7 @@ def _test_deps(): def _dev(envdir='env'): envdir = _env(envdir) + _install_tox() run('tox', '--notest', '--skip-missing-interpreters') return envdir @@ -129,6 +133,7 @@ def clean_sphinx(): def _tox(*args, **kw): _env() + _install_tox() kw.setdefault('silent', False) shell('tox', '--skip-missing-interpreters', '--', *args, **kw)