diff --git a/docs/conftest.py b/docs/conftest.py new file mode 100644 index 0000000..fc9ddc7 --- /dev/null +++ b/docs/conftest.py @@ -0,0 +1,12 @@ +from doctest import ELLIPSIS +from sybil import Sybil +from sybil.parsers.codeblock import CodeBlockParser +from sybil.parsers.doctest import DocTestParser, FIX_BYTE_UNICODE_REPR + +pytest_collect_file = Sybil( + parsers=[ + DocTestParser(optionflags=ELLIPSIS | FIX_BYTE_UNICODE_REPR), + CodeBlockParser(future_imports=['print_function']), + ], + pattern='index.rst', +).pytest() diff --git a/docs/examples/simple_example.py b/docs/examples/simple_example.py deleted file mode 100644 index 3ed0e37..0000000 --- a/docs/examples/simple_example.py +++ /dev/null @@ -1,48 +0,0 @@ -from wired import ServiceRegistry - - -class Greeter: - def __init__(self, greeting): - self.greeting = greeting - - def __call__(self): - return f'{self.greeting} !!' - - -def app_setup(): - # Make the application's registry - registry = ServiceRegistry() - - # Greeters are nice...they greet people! - greeter = Greeter(greeting='Hello') - - # Register it as a singleton using its class for the "key" - registry.register_singleton(greeter, Greeter) - - return registry - - -def greet_a_customer(container): - - # Get the registered greeter, do the greeting - the_greeter = container.get(Greeter) - greeting = the_greeter() - - return greeting - - -def main(): - # Setup the application - registry = app_setup() - - # A customer comes in, handle the steps in the greeting process - # as a "container". - container = registry.create_container() - greeting = greet_a_customer(container) - - # The "request" was handled, return it - print(greeting) - - -if __name__ == '__main__': - main() diff --git a/docs/index.rst b/docs/index.rst index 6fdab1f..8f5dfc6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -51,22 +51,53 @@ Once you have a copy of the source, you can install it with: .. _Github repo: https://github.com/mmerickel/wired -Quick Usage -=========== +Example +======= -Imagine an application where customers walk in the door and you want to greet them with a Greeter. This application is simple: there's only one Greeter. +Imagine an application where customers walk in the door and you want a `Greeter` to greet them: -To do this, we: +.. code-block:: python -- Setup the application: make a "registry" and register some things (a "singleton" to hold the ``Greeter``) + class Greeter: + def __init__(self, greeting): + self.greeting = greeting -- Start processing requests (greet someone) by getting stuff we need to process the request + def __call__(self): + return self.greeting + ' !!' -- "Get stuff we need" by asking *the system* for what we need (a ``Greeter``) +Our application is pluggable: it has a "registry" which processes operations in a "container": -For a deeper dive, try :doc:`the tutorial <./tutorial/index>`. +>>> from wired import ServiceRegistry +>>> registry = ServiceRegistry() -.. literalinclude:: examples/simple_example.py +As part of application setup, stuff gets put in the app's registry. This application is simple: there's only one Greeter, so we register a "singleton" `Greeter` instance: + +.. code-block:: python + + # Greeters are nice...they greet people! + greeter = Greeter(greeting='Hello') + + # Register it as a singleton using its class for the "key" + registry.register_singleton(greeter, Greeter) + +Here is a function that greets a customer as part of a "container" operation: + +.. code-block:: python + + def greet_a_customer(container): + + # Ask the *system* via the container to find the `Greeter` for us + the_greeter = container.get(Greeter) + greeting = the_greeter() + + return greeting + +The app processes a customer by making a container and doing the operation: + +>>> container = registry.create_container() +>>> greeting = greet_a_customer(container) +>>> print(greeting) +Hello !! More Information ================ diff --git a/setup.cfg b/setup.cfg index 553321d..efdf395 100644 --- a/setup.cfg +++ b/setup.cfg @@ -20,3 +20,5 @@ xfail_strict = true testpaths = src/wired tests + docs + diff --git a/setup.py b/setup.py index b7e0f19..7b51333 100644 --- a/setup.py +++ b/setup.py @@ -13,7 +13,7 @@ def readfile(name): docs_require = ['Sphinx', 'sphinx_rtd_theme'] -tests_require = ['pytest', 'pytest-cov'] +tests_require = ['pytest', 'pytest-cov', 'sybil'] setup( name='wired', diff --git a/tests/docs_examples/conftest.py b/tests/docs_examples/conftest.py deleted file mode 100644 index 510c540..0000000 --- a/tests/docs_examples/conftest.py +++ /dev/null @@ -1,15 +0,0 @@ -import os -import sys - -import pytest - -if sys.version_info < (3, 7): # pragma: no cover - collect_ignore_glob = ['*.py'] - - -@pytest.fixture(scope="session", autouse=True) -def examples_path(): - tutorial_path = os.path.abspath( - os.path.join(os.path.dirname(__file__), '../../docs/examples') - ) - sys.path.insert(0, tutorial_path) diff --git a/tests/docs_examples/test_simple_example.py b/tests/docs_examples/test_simple_example.py deleted file mode 100644 index 1a0ac69..0000000 --- a/tests/docs_examples/test_simple_example.py +++ /dev/null @@ -1,7 +0,0 @@ -def test_greet_a_customer(capsys): - from simple_example import main - - main() - - captured = capsys.readouterr() - assert captured.out == "Hello !!\n"