Skip to content

docs(readme): add block code type #48

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wbarnha merged 2 commits into from
Feb 22, 2024
Merged

docs(readme): add block code type #48

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c9b22d9
docs(readme): add block code type
manawasp Feb 21, 2024
16129b6
Merge branch 'master' into docs/update-readme-code-synthax
wbarnha Feb 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 79 additions & 34 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
Why the fork
============

We have decided to fork the original *Mode* project because there is a critical process of releasing new versions which causes uncertainty in the community. Everybody is welcome to contribute to this *fork*, and you can be added as a manitainer.
We have decided to fork the original *Mode* project because there is a critical process of releasing new versions which causes uncertainty in the community. Everybody is welcome to contribute to this *fork*, and you can be added as a maintainer.

We want to:

Expand All @@ -33,7 +33,9 @@ it much easier to use.
In Mode your program is built out of services that you can start, stop,
restart and supervise.

A service is just a class::
A service is just a class:

.. code-block:: python

class PageViewCache(Service):
redis: Redis = None
Expand All @@ -51,7 +53,9 @@ A service is just a class::
Services are started, stopped and restarted and have
callbacks for those actions.

It can start another service::
It can start another service:

.. code-block:: python

class App(Service):
page_view_cache: PageViewCache = None
Expand All @@ -63,7 +67,9 @@ It can start another service::
def page_view_cache(self) -> PageViewCache:
return PageViewCache()

It can include background tasks::
It can include background tasks:

.. code-block:: python

class PageViewCache(Service):

Expand All @@ -78,15 +84,17 @@ Worker
Mode optionally provides a worker that you can use to start the program,
with support for logging, blocking detection, remote debugging and more.

To start a worker add this to your program::
To start a worker add this to your program:

.. code-block:: python

if __name__ == '__main__':
from mode import Worker
Worker(Service(), loglevel="info").execute_from_commandline()

Then execute your program to start the worker:

.. sourcecode:: console
.. code-block:: console

$ python examples/tutorial.py
[2018-03-27 15:47:12,159: INFO]: [^Worker]: Starting...
Expand All @@ -101,7 +109,7 @@ Worker

To stop it hit ``Control-c``:

.. sourcecode:: console
.. code-block:: console

[2018-03-27 15:55:08,084: INFO]: [^Worker]: Stopping on signal received...
[2018-03-27 15:55:08,084: INFO]: [^Worker]: Stopping...
Expand Down Expand Up @@ -133,12 +141,14 @@ Beacons
This requires you to have the ``pydot`` library and GraphViz
installed:

.. sourcecode:: console
.. code-block:: console

$ pip install pydot

Let's change the app service class to dump the graph to an image
at startup::
at startup:

.. code-block:: python

class AppService(Service):

Expand All @@ -159,7 +169,10 @@ Creating a Service
==================

To define a service, simply subclass and fill in the methods
to do stuff as the service is started/stopped etc.::
to do stuff as the service is started/stopped etc.:


.. code-block:: python

class MyService(Service):

Expand All @@ -172,12 +185,16 @@ to do stuff as the service is started/stopped etc.::
async def on_stop(self) -> None:
print('Im stopping now')

To start the service, call ``await service.start()``::
To start the service, call ``await service.start()``:

.. code-block:: python

await service.start()

Or you can use ``mode.Worker`` (or a subclass of this) to start your
services-based asyncio program from the console::
services-based asyncio program from the console:

.. code-block:: python

if __name__ == '__main__':
import mode
Expand All @@ -194,14 +211,18 @@ It's a Graph!

Services can start other services, coroutines, and background tasks.

1) Starting other services using ``add_depenency``::
1) Starting other services using ``add_depenency``:

.. code-block:: python

class MyService(Service):

def __post_init__(self) -> None:
self.add_dependency(OtherService(loop=self.loop))
self.add_dependency(OtherService(loop=self.loop))

2) Start a list of services using ``on_init_dependencies``:

2) Start a list of services using ``on_init_dependencies``::
.. code-block:: python

class MyService(Service):

Expand All @@ -212,7 +233,9 @@ Services can start other services, coroutines, and background tasks.
ServiceC(loop=self.loop),
]

3) Start a future/coroutine (that will be waited on to complete on stop)::
3) Start a future/coroutine (that will be waited on to complete on stop):

.. code-block:: python

class MyService(Service):

Expand All @@ -222,7 +245,9 @@ Services can start other services, coroutines, and background tasks.
async def my_coro(self) -> None:
print('Executing coroutine')

4) Start a background task::
4) Start a background task:

.. code-block:: python

class MyService(Service):

Expand All @@ -231,7 +256,9 @@ Services can start other services, coroutines, and background tasks.
print('Executing coroutine')


5) Start a background task that keeps running::
5) Start a background task that keeps running:

.. code-block:: python

class MyService(Service):

Expand All @@ -251,7 +278,9 @@ Installation
You can install Mode either via the Python Package Index (PyPI)
or from source.

To install using `pip`::
To install using `pip`:

.. code-block:: console

$ pip install -U mode-streaming

Expand All @@ -263,12 +292,14 @@ Downloading and installing from source
Download the latest version of Mode from
http://pypi.org/project/mode-streaming

You can install it by doing the following::
You can install it by doing the following:

$ tar xvfz mode-streaming-0.2.1.tar.gz
$ cd mode-0.2.1
$ python setup.py build
# python setup.py install
.. code-block:: console

$ tar xvfz mode-streaming-0.2.1.tar.gz
$ cd mode-0.2.1
$ python setup.py build
# python setup.py install

The last command must be executed as a privileged user if
you are not currently using a virtualenv.
Expand All @@ -282,7 +313,9 @@ With pip
~~~~~~~~

You can install the latest snapshot of Mode using the following
pip command::
pip command:

.. code-block:: console

$ pip install mode-streaming

Expand All @@ -302,13 +335,15 @@ This works with any blocking Python library that can work with gevent.
Using gevent requires you to install the ``aiogevent`` module,
and you can install this as a bundle with Mode:

.. sourcecode:: console
.. code-block:: console

$ pip install -U mode-streaming[gevent]

Then to actually use gevent as the event loop you have to
execute the following in your entrypoint module (usually where you
start the worker), before any other third party libraries are imported::
start the worker), before any other third party libraries are imported:

.. code-block:: python

#!/usr/bin/env python3
import mode.loop
Expand All @@ -327,13 +362,15 @@ This works with any blocking Python library that can work with eventlet.
Using eventlet requires you to install the ``aioeventlet`` module,
and you can install this as a bundle with Mode:

.. sourcecode:: console
.. code-block:: console

$ pip install -U mode-streaming[eventlet]

Then to actually use eventlet as the event loop you have to
execute the following in your entrypoint module (usually where you
start the worker), before any other third party libraries are imported::
start the worker), before any other third party libraries are imported:

.. code-block:: python

#!/usr/bin/env python3
import mode.loop
Expand Down Expand Up @@ -365,26 +402,34 @@ Here are some of the steps required to accomplish this:

- Source code transformation to rewrite variable annotations to comments

for example, the code::
for example, the code:

.. code-block:: python

class Point:
x: int = 0
y: int = 0

must be rewritten into::
must be rewritten into:

.. code-block:: python

class Point:
x = 0 # type: int
y = 0 # type: int

- Source code transformation to rewrite async functions

for example, the code::
for example, the code:

.. code-block:: python

async def foo():
await asyncio.sleep(1.0)

must be rewritten into::
must be rewritten into:

.. code-block:: python

@coroutine
def foo():
Expand All @@ -402,7 +447,7 @@ At Shutdown I get lots of warnings, what is this about?

If you get warnings such as this at shutdown:

.. sourcecode:: text
.. code-block:: text

Task was destroyed but it is pending!
task: <Task pending coro=<Service._execute_task() running at /opt/devel/mode/mode/services.py:643> wait_for=<Future pending cb=[<TaskWakeupMethWrapper object at 0x1100a7468>()]>>
Expand Down