Pyjo-Reactor-Gevent 0.1.0__tar.gz

pyjo_reactor_gevent-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+/build/
+/dist/
+/docs/_build/
+
+# Virtual environments of uv
+.venv
+.venv-*
+
+# Caches of the tools
+.ruff_cache/
+
+# macOS
+.DS_Store

pyjo_reactor_gevent-0.1.0/.proverc

@@ -0,0 +1,2 @@
+--ext=py
+--exec=python

pyjo_reactor_gevent-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+		       The Artistic License 2.0
+
+	    Copyright (c) 2000-2006, The Perl Foundation.
+
+     Everyone is permitted to copy and distribute verbatim copies
+      of this license document, but changing it is not allowed.
+
+Preamble
+
+This license establishes the terms under which a given free software
+Package may be copied, modified, distributed, and/or redistributed.
+The intent is that the Copyright Holder maintains some artistic
+control over the development of that Package while still keeping the
+Package available as open source and free software.
+
+You are always permitted to make arrangements wholly outside of this
+license directly with the Copyright Holder of a given Package.  If the
+terms of this license do not permit the full use that you propose to
+make of the Package, you should contact the Copyright Holder and seek
+a different licensing arrangement.
+
+Definitions
+
+    "Copyright Holder" means the individual(s) or organization(s)
+    named in the copyright notice for the entire Package.
+
+    "Contributor" means any party that has contributed code or other
+    material to the Package, in accordance with the Copyright Holder's
+    procedures.
+
+    "You" and "your" means any person who would like to copy,
+    distribute, or modify the Package.
+
+    "Package" means the collection of files distributed by the
+    Copyright Holder, and derivatives of that collection and/or of
+    those files. A given Package may consist of either the Standard
+    Version, or a Modified Version.
+
+    "Distribute" means providing a copy of the Package or making it
+    accessible to anyone else, or in the case of a company or
+    organization, to others outside of your company or organization.
+
+    "Distributor Fee" means any fee that you charge for Distributing
+    this Package or providing support for this Package to another
+    party.  It does not mean licensing fees.
+
+    "Standard Version" refers to the Package if it has not been
+    modified, or has been modified only in ways explicitly requested
+    by the Copyright Holder.
+
+    "Modified Version" means the Package, if it has been changed, and
+    such changes were not explicitly requested by the Copyright
+    Holder.
+
+    "Original License" means this Artistic License as Distributed with
+    the Standard Version of the Package, in its current version or as
+    it may be modified by The Perl Foundation in the future.
+
+    "Source" form means the source code, documentation source, and
+    configuration files for the Package.
+
+    "Compiled" form means the compiled bytecode, object code, binary,
+    or any other form resulting from mechanical transformation or
+    translation of the Source form.
+
+
+Permission for Use and Modification Without Distribution
+
+(1)  You are permitted to use the Standard Version and create and use
+Modified Versions for any purpose without restriction, provided that
+you do not Distribute the Modified Version.
+
+
+Permissions for Redistribution of the Standard Version
+
+(2)  You may Distribute verbatim copies of the Source form of the
+Standard Version of this Package in any medium without restriction,
+either gratis or for a Distributor Fee, provided that you duplicate
+all of the original copyright notices and associated disclaimers.  At
+your discretion, such verbatim copies may or may not include a
+Compiled form of the Package.
+
+(3)  You may apply any bug fixes, portability changes, and other
+modifications made available from the Copyright Holder.  The resulting
+Package will still be considered the Standard Version, and as such
+will be subject to the Original License.
+
+
+Distribution of Modified Versions of the Package as Source
+
+(4)  You may Distribute your Modified Version as Source (either gratis
+or for a Distributor Fee, and with or without a Compiled form of the
+Modified Version) provided that you clearly document how it differs
+from the Standard Version, including, but not limited to, documenting
+any non-standard features, executables, or modules, and provided that
+you do at least ONE of the following:
+
+    (a)  make the Modified Version available to the Copyright Holder
+    of the Standard Version, under the Original License, so that the
+    Copyright Holder may include your modifications in the Standard
+    Version.
+
+    (b)  ensure that installation of your Modified Version does not
+    prevent the user installing or running the Standard Version. In
+    addition, the Modified Version must bear a name that is different
+    from the name of the Standard Version.
+
+    (c)  allow anyone who receives a copy of the Modified Version to
+    make the Source form of the Modified Version available to others
+    under
+
+	(i)  the Original License or
+
+	(ii)  a license that permits the licensee to freely copy,
+	modify and redistribute the Modified Version using the same
+	licensing terms that apply to the copy that the licensee
+	received, and requires that the Source form of the Modified
+	Version, and of any works derived from it, be made freely
+	available in that license fees are prohibited but Distributor
+	Fees are allowed.
+
+
+Distribution of Compiled Forms of the Standard Version
+or Modified Versions without the Source
+
+(5)  You may Distribute Compiled forms of the Standard Version without
+the Source, provided that you include complete instructions on how to
+get the Source of the Standard Version.  Such instructions must be
+valid at the time of your distribution.  If these instructions, at any
+time while you are carrying out such distribution, become invalid, you
+must provide new instructions on demand or cease further distribution.
+If you provide valid instructions or cease distribution within thirty
+days after you become aware that the instructions are invalid, then
+you do not forfeit any of your rights under this license.
+
+(6)  You may Distribute a Modified Version in Compiled form without
+the Source, provided that you comply with Section 4 with respect to
+the Source of the Modified Version.
+
+
+Aggregating or Linking the Package
+
+(7)  You may aggregate the Package (either the Standard Version or
+Modified Version) with other packages and Distribute the resulting
+aggregation provided that you do not charge a licensing fee for the
+Package.  Distributor Fees are permitted, and licensing fees for other
+components in the aggregation are permitted. The terms of this license
+apply to the use and Distribution of the Standard or Modified Versions
+as included in the aggregation.
+
+(8) You are permitted to link Modified and Standard Versions with
+other works, to embed the Package in a larger work of your own, or to
+build stand-alone binary or bytecode versions of applications that
+include the Package, and Distribute the result without restriction,
+provided the result does not expose a direct interface to the Package.
+
+
+Items That are Not Considered Part of a Modified Version
+
+(9) Works (including, but not limited to, modules and scripts) that
+merely extend or make use of the Package, do not, by themselves, cause
+the Package to be a Modified Version.  In addition, such works are not
+considered parts of the Package itself, and are not subject to the
+terms of this license.
+
+
+General Provisions
+
+(10)  Any use, modification, and distribution of the Standard or
+Modified Versions is governed by this Artistic License. By using,
+modifying or distributing the Package, you accept this license. Do not
+use, modify, or distribute the Package, if you do not accept this
+license.
+
+(11)  If your Modified Version has been derived from a Modified
+Version made by someone other than you, you are nevertheless required
+to ensure that your Modified Version complies with the requirements of
+this license.
+
+(12)  This license does not grant you the right to use any trademark,
+service mark, tradename, or logo of the Copyright Holder.
+
+(13)  This license includes the non-exclusive, worldwide,
+free-of-charge patent license to make, have made, use, offer to sell,
+sell, import and otherwise transfer the Package with respect to any
+patent claims licensable by the Copyright Holder that are necessarily
+infringed by the Package. If you institute patent litigation
+(including a cross-claim or counterclaim) against any party alleging
+that the Package constitutes direct or contributory patent
+infringement, then this Artistic License to you shall terminate on the
+date that such litigation is filed.
+
+(14)  Disclaimer of Warranty:
+THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS
+IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR
+NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL
+LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL
+BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pyjo_reactor_gevent-0.1.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.5
+Name: Pyjo-Reactor-Gevent
+Version: 0.1.0
+Summary: Low level event reactor with gevent support for Pyjoyment.
+Project-URL: Homepage, https://github.com/pyjoyment/Pyjo-Reactor-Gevent
+Project-URL: Documentation, https://pyjoyment.readthedocs.io/projects/pyjo-reactor-gevent/en/stable/
+Author-email: Piotr Roszatycki <piotr.roszatycki@gmail.com>
+License-Expression: Artistic-2.0
+License-File: LICENSE
+Keywords: gevent,greenlet,pyjoyment,reactor
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.12
+Requires-Dist: gevent>=26.9.0
+Requires-Dist: pyjoyment>=0.3.0
+Description-Content-Type: text/markdown
+
+[![Home](https://img.shields.io/badge/%F0%9F%8F%A0-Pyjoyment-02a7a0)](https://github.com/pyjoyment/Pyjoyment)
+[![GitHub](https://img.shields.io/github/stars/pyjoyment/Pyjo-Reactor-Gevent?style=flat&label=GitHub%20%E2%AD%90&logo=github)](https://github.com/pyjoyment/Pyjo-Reactor-Gevent)
+[![Documentation](https://img.shields.io/badge/docs-Read_the_Docs-blue?logo=readthedocs&logoColor=white)](https://pyjoyment.readthedocs.io/projects/pyjo-reactor-gevent/en/stable/)
+[![License](https://img.shields.io/github/license/pyjoyment/Pyjo-Reactor-Gevent.svg)](https://github.com/pyjoyment/Pyjo-Reactor-Gevent/blob/main/LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/Pyjo-Reactor-Gevent?logo=pypi&logoColor=white)](https://pypi.org/project/Pyjo-Reactor-Gevent/)
+[![Tests](https://github.com/pyjoyment/Pyjo-Reactor-Gevent/actions/workflows/tests.yaml/badge.svg?branch=main)](https://github.com/pyjoyment/Pyjo-Reactor-Gevent/actions/workflows/tests.yaml)
+[![Trunk Check](https://github.com/pyjoyment/Pyjo-Reactor-Gevent/actions/workflows/trunk-check.yaml/badge.svg?branch=main)](https://github.com/pyjoyment/Pyjo-Reactor-Gevent/actions/workflows/trunk-check.yaml)
+
+# Pyjo-Reactor-Gevent
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/pyjoyment/Pyjoyment/main/Pyjoyment/resources/public/pyjo/logo-white-4x.png">
+    <img src="https://raw.githubusercontent.com/pyjoyment/Pyjoyment/main/Pyjoyment/resources/public/pyjo/logo-black-4x.png" alt="Pyjoyment" width="322">
+  </picture>
+</p>
+
+Low level event reactor with [gevent](https://www.gevent.org) support for
+[Pyjoyment](https://github.com/pyjoyment/Pyjoyment).
+
+`Pyjo.Reactor.Gevent` is a reactor of Pyjoyment on the hub of gevent, whose
+loop of libev or libuv watches the handles and runs the timers, so that the
+servers of Pyjoyment, `daemon`, `prefork` and `prethread`, and its user agent
+run along with the greenlets of a program of gevent.
+
+## Installation
+
+From [PyPI](https://pypi.org/project/Pyjo-Reactor-Gevent/), with
+[Pyjoyment](https://pypi.org/project/Pyjoyment/) and
+[gevent](https://pypi.org/project/gevent/), which it depends on:
+
+```sh
+pip install Pyjo-Reactor-Gevent
+```
+
+or, in a project managed with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv add Pyjo-Reactor-Gevent
+```
+
+The development version is installed from the Git repository:
+
+```sh
+pip install git+https://github.com/pyjoyment/Pyjo-Reactor-Gevent
+```
+
+## Usage
+
+Select the reactor with `PYJO_REACTOR` before `Pyjo.IOLoop` is loaded:
+
+```sh
+PYJO_REACTOR=Pyjo.Reactor.Gevent python myapp.py daemon
+PYJO_REACTOR=Pyjo.Reactor.Gevent python myapp.py prefork
+```
+
+The reactor runs in the greenlet that starts it, and the other greenlets of the
+program run while it waits for events. A blocking request of the user agent
+waits in the greenlet that makes it, without blocking the others.
+
+gevent runs on libev by default. Its loop of libuv needs
+[cffi](https://pypi.org/project/cffi/):
+
+```sh
+pip install Pyjo-Reactor-Gevent cffi
+GEVENT_LOOP=libuv-cffi PYJO_REACTOR=Pyjo.Reactor.Gevent python myapp.py daemon
+```
+
+With `gevent.monkey.patch_all()`, the threads of the program are greenlets, so
+each greenlet has a `Pyjo.IOLoop.singleton` of its own, and
+`Pyjo.Server.Prethread` and `Pyjo.IOLoop.ChildProcess` do not work.
+
+## Examples
+
+`examples/hello_world_gevent.py` runs `Pyjo.HelloWorld` on the server of
+Pyjoyment on gevent until the signal `INT` or `TERM`, in a `with` block, which
+closes the listen sockets of the server at its end:
+
+```python
+import os
+
+
+# The reactor of Pyjoyment on gevent, selected before Pyjo.IOLoop is loaded
+os.environ['PYJO_REACTOR'] = 'Pyjo.Reactor.Gevent'
+
+import Pyjo.HelloWorld  # noqa: E402
+import Pyjo.Server.Daemon  # noqa: E402
+
+
+# The server of Pyjoyment on gevent, until the signal INT or TERM, which closes its listen sockets at the end of the block
+with Pyjo.Server.Daemon.new(app=Pyjo.HelloWorld.new(), listen=['http://*:3000']) as daemon:
+    daemon.run()
+```
+
+```console
+$ python examples/hello_world_gevent.py
+Web application available at http://127.0.0.1:3000
+```
+
+```console
+$ curl http://127.0.0.1:3000/
+Your Pyjo is working!
+```
+
+`examples/loopback_gevent.py` is a server of Pyjoyment and its user agent on
+the hub of gevent, a blocking request, which runs the event loop until the
+response, and the class of the reactor and whether it runs on the hub of
+gevent, which Build checks with the wheel:
+
+```python
+import os
+
+
+# The reactor of Pyjoyment on gevent, selected before Pyjo.IOLoop is loaded
+os.environ['PYJO_REACTOR'] = 'Pyjo.Reactor.Gevent'
+
+import Pyjo.HelloWorld  # noqa: E402
+import Pyjo.IOLoop  # noqa: E402
+import Pyjo.Server.Daemon  # noqa: E402
+import Pyjo.UserAgent  # noqa: E402
+
+import gevent  # noqa: E402
+
+
+# The server, on a port that the system picks, and the user agent, in the same event loop, which close their sockets at
+# the end of the block
+with (
+    Pyjo.Server.Daemon.new(app=Pyjo.HelloWorld.new(), listen=['http://127.0.0.1'], silent=True) as daemon,
+    Pyjo.UserAgent.new(ioloop=Pyjo.IOLoop.singleton) as ua,
+):
+    # A blocking request, which runs the event loop of the server on the hub of gevent until the response
+    tx = ua.get(f'http://127.0.0.1:{daemon.start().ports()[0]}/')
+    reactor = Pyjo.IOLoop.singleton.reactor
+    print(type(reactor).__name__, 'gevent' if getattr(reactor, 'hub', None) is gevent.get_hub() else 'other')
+    print(tx.result.code, tx.result.text)
+```
+
+```console
+$ python examples/loopback_gevent.py
+Pyjo_Reactor_Gevent gevent
+200 Your Pyjo is working!
+```
+
+`examples/greenlets_gevent.py` is a server of Pyjoyment in the main greenlet,
+along with two greenlets of the application that request it, one with a socket
+of gevent and one with a blocking request of the user agent of Pyjoyment:
+
+```python
+import os
+
+
+# The reactor of Pyjoyment on gevent, selected before Pyjo.IOLoop is loaded
+os.environ['PYJO_REACTOR'] = 'Pyjo.Reactor.Gevent'
+
+import Pyjo.HelloWorld  # noqa: E402
+import Pyjo.IOLoop  # noqa: E402
+import Pyjo.Server.Daemon  # noqa: E402
+import Pyjo.UserAgent  # noqa: E402
+
+import gevent  # noqa: E402
+import gevent.socket  # noqa: E402
+
+
+# A greenlet with a socket of gevent, which waits in the hub of gevent, where the server of Pyjoyment runs
+def with_socket(port):
+    with gevent.socket.create_connection(('127.0.0.1', port)) as sock:
+        sock.sendall(b'GET / HTTP/1.1\r\nHost: 127.0.0.1\r\nConnection: close\r\n\r\n')
+        response = b''
+        while b'\r\n' not in response and (chunk := sock.recv(4096)):
+            response += chunk
+    status = response.split(b'\r\n')[0].decode()
+    return f'gevent.socket: {status}'
+
+
+# A greenlet with a blocking request of the user agent of Pyjoyment, whose event loop of its own waits in the greenlet
+def with_user_agent(port):
+    with Pyjo.UserAgent.new() as ua:
+        tx = ua.get(f'http://127.0.0.1:{port}/')
+    return f'Pyjo.UserAgent: {tx.result.code} {tx.result.text}'
+
+
+# The server, on a port that the system picks, which runs in the main greenlet until the greenlets are done, and closes its
+# listen sockets at the end of the block
+with Pyjo.Server.Daemon.new(app=Pyjo.HelloWorld.new(), listen=['http://127.0.0.1'], silent=True) as daemon:
+    port = daemon.start().ports()[0]
+    greenlets = [gevent.spawn(with_socket, port), gevent.spawn(with_user_agent, port)]
+    gevent.spawn(lambda: (gevent.joinall(greenlets), Pyjo.IOLoop.stop()))
+    Pyjo.IOLoop.start()
+    for greenlet in greenlets:
+        print(greenlet.value)
+```
+
+```console
+$ python examples/greenlets_gevent.py
+gevent.socket: HTTP/1.1 200 OK
+Pyjo.UserAgent: 200 Your Pyjo is working!
+```
+
+## Documentation
+
+The API of the module and the examples are on
+[Read the Docs](https://pyjoyment.readthedocs.io/projects/pyjo-reactor-gevent/en/stable/).
+
+## Status
+
+A reactor of Pyjoyment in a distribution of its own, as
+[Pyjo-Reactor-Twisted](https://github.com/pyjoyment/Pyjo-Reactor-Twisted) and
+[Pyjo-Reactor-Uvloop](https://github.com/pyjoyment/Pyjo-Reactor-Uvloop).