From c4554a5170ea7fd5bf4c2ad4ddb678d4618a5c40 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Sun, 21 Apr 2019 12:09:25 -0400 Subject: [PATCH 1/5] Let's give Sybil a try. docs/index.rst works great but usage.rst should not be tested. --- docs/conftest.py | 12 ++++ docs/examples/simple_example.py | 48 ------------- docs/index.rst | 79 +++++++++++++++++++--- setup.py | 2 +- tests/docs_examples/conftest.py | 15 ---- tests/docs_examples/test_simple_example.py | 7 -- 6 files changed, 83 insertions(+), 80 deletions(-) create mode 100644 docs/conftest.py delete mode 100644 docs/examples/simple_example.py delete mode 100644 tests/docs_examples/conftest.py delete mode 100644 tests/docs_examples/test_simple_example.py 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..80ca741 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -51,22 +51,83 @@ 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 f'{self.greeting} !!' -- "Get stuff we need" by asking *the system* for what we need (a ``Greeter``) +We are writing a pluggable application which 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() + +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 !! + + +Sample Documentation +==================== + +Let's put something in the Sybil document's namespace: + +.. invisible-code-block: python + + remember_me = b'see how namespaces work?' + +Suppose we define a function, convoluted and pointless but shows stuff nicely: + +.. code-block:: python + + import sys + + def prefix_and_print(message): + print('prefix:', message.decode('ascii')) + +Now we can use a doctest REPL to show it in action: + +>>> prefix_and_print(remember_me) +prefix: see how namespaces work? + +The namespace carries across from example to example, no matter what parser: + +>>> remember_me +b'see how namespaces work?' -.. literalinclude:: examples/simple_example.py More Information ================ diff --git a/setup.py b/setup.py index e709bb5..87626ab 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" From 49ecd2e614c72498ed552fee5159edd580e42872 Mon Sep 17 00:00:00 2001 From: Chris Withers Date: Mon, 22 Apr 2019 15:33:47 +0100 Subject: [PATCH 2/5] get all sybil tests running when using pycharm's pytest runner from the root of the clone --- docs/conftest.py => conftest.py | 2 +- setup.cfg | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) rename docs/conftest.py => conftest.py (93%) diff --git a/docs/conftest.py b/conftest.py similarity index 93% rename from docs/conftest.py rename to conftest.py index fc9ddc7..65935e3 100644 --- a/docs/conftest.py +++ b/conftest.py @@ -8,5 +8,5 @@ DocTestParser(optionflags=ELLIPSIS | FIX_BYTE_UNICODE_REPR), CodeBlockParser(future_imports=['print_function']), ], - pattern='index.rst', + pattern='*.rst', ).pytest() 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 + From 8baf9df546f6848466d504dc08cfa7b76b64c78b Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Mon, 22 Apr 2019 20:20:02 -0400 Subject: [PATCH 3/5] Have docs/conftest.py which only looks for now in index.rst files. --- conftest.py => docs/conftest.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename conftest.py => docs/conftest.py (93%) diff --git a/conftest.py b/docs/conftest.py similarity index 93% rename from conftest.py rename to docs/conftest.py index 65935e3..fc9ddc7 100644 --- a/conftest.py +++ b/docs/conftest.py @@ -8,5 +8,5 @@ DocTestParser(optionflags=ELLIPSIS | FIX_BYTE_UNICODE_REPR), CodeBlockParser(future_imports=['print_function']), ], - pattern='*.rst', + pattern='index.rst', ).pytest() From 6a42ae39f02748136d55cbc4a18d3a874ca579f7 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Sat, 27 Apr 2019 11:08:56 -0400 Subject: [PATCH 4/5] Stop using f-strings since this has to run on older Python. --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 80ca741..c5afa12 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -63,7 +63,7 @@ Imagine an application where customers walk in the door and you want a `Greeter` self.greeting = greeting def __call__(self): - return f'{self.greeting} !!' + return self.greeting + ' !!' We are writing a pluggable application which has a "registry" which processes operations in a "container": From 0d9401a80d08f0f5607d362732820462489f8961 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Sat, 27 Apr 2019 11:18:16 -0400 Subject: [PATCH 5/5] Clean up some text on the home page, remove the accidental Sybil example. --- docs/index.rst | 32 +------------------------------- 1 file changed, 1 insertion(+), 31 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index c5afa12..8f5dfc6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -65,7 +65,7 @@ Imagine an application where customers walk in the door and you want a `Greeter` def __call__(self): return self.greeting + ' !!' -We are writing a pluggable application which has a "registry" which processes operations in a "container": +Our application is pluggable: it has a "registry" which processes operations in a "container": >>> from wired import ServiceRegistry >>> registry = ServiceRegistry() @@ -99,36 +99,6 @@ The app processes a customer by making a container and doing the operation: >>> print(greeting) Hello !! - -Sample Documentation -==================== - -Let's put something in the Sybil document's namespace: - -.. invisible-code-block: python - - remember_me = b'see how namespaces work?' - -Suppose we define a function, convoluted and pointless but shows stuff nicely: - -.. code-block:: python - - import sys - - def prefix_and_print(message): - print('prefix:', message.decode('ascii')) - -Now we can use a doctest REPL to show it in action: - ->>> prefix_and_print(remember_me) -prefix: see how namespaces work? - -The namespace carries across from example to example, no matter what parser: - ->>> remember_me -b'see how namespaces work?' - - More Information ================