Metadata-Version: 2.1
Name: poorconn
Version: 0.1
Summary: Simulating poor network connections.
Home-page: https://poorconn.topbug.net
Author: Hong Xu
Author-email: hong@topbug.net
License: LGPLv3+
Project-URL: Source, https://gitlab.com/xuhdev/poorconn
Project-URL: Tracker, https://gitlab.com/xuhdev/poorconn/issues
Keywords: socket,test,unittest
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: License :: DFSG approved
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/x-rst
Provides-Extra: full
Requires-Dist: pytest (>=6.2) ; extra == 'full'

.. readme-roles

.. role:: doc(literal)
.. role:: func(literal)
.. role:: mod(literal)

.. readme-main

Poorconn: Simulating Poor Network Conditions
============================================

.. image:: https://img.shields.io/pypi/v/poorconn.svg
   :target: https://pypi.python.org/pypi/poorconn
   :alt: PyPI

.. image:: https://img.shields.io/pypi/pyversions/poorconn.svg
   :target: https://pypi.python.org/pypi/poorconn
   :alt: PyPI - Python Versions

.. image:: https://img.shields.io/pypi/implementation/poorconn
   :target: https://pypi.python.org/pypi/poorconn
   :alt: PyPI - Implementation

.. image:: https://img.shields.io/badge/-Documentation-informational
   :target: https://poorconn.topbug.net
   :alt: Documentation

.. image:: https://img.shields.io/pypi/l/poorconn
   :target: https://gitlab.com/xuhdev/poorconn/-/blob/master/COPYING
   :alt: PyPI - License

.. image:: https://gitlab.com/xuhdev/poorconn/badges/master/pipeline.svg
   :target: https://gitlab.com/xuhdev/poorconn/-/commits/master
   :alt: Pipeline Status

.. image:: https://gitlab.com/xuhdev/poorconn/badges/master/coverage.svg
   :target: https://gitlab.com/xuhdev/poorconn/-/commits/master
   :alt: Coverage

Poorconn is a Python package that simulates poor network conditions. It is suitable for testing purposes, for both
Python and non-Python projects.

It is capable of simulating the following poor network conditions:

- Throttled network connections. (:func:`delay_before_sending`, :func:`delay_before_sending_upon_acceptance`)
- Servers that cut off connections immediately upon accepting them. (:func:`close_upon_accepting`)
- Connections that are initially slow, but become normal subsequently. (:func:`delay_before_sending_once`,
  :func:`delay_before_sending_upon_acceptance_once`)


.. _quickstart:

Quickstart
----------

Install this package via

.. code-block:: console

   $ pip install 'poorconn[full]'  # or "pip install poorconn" if you don't need pytest support

The following example starts a local HTTP server at port 8000 that always closes connections upon accepting them:

.. code-block:: python

   from http.server import HTTPServer, SimpleHTTPRequestHandler
   from poorconn import close_upon_accepting, make_socket_patchable

   # Start a local HTTP server that always closes connections upon established
   with HTTPServer(("localhost", 8000), SimpleHTTPRequestHandler) as httpd:
       httpd.socket = make_socket_patchable(httpd.socket)
       close_upon_accepting(httpd.socket)
       httpd.serve_forever()

After running the code above, connections from a client would establish but fail to communicate subsequently:

.. code-block:: console

   $ wget -t 1 http://127.0.0.1:8000
   Connecting to 127.0.0.1:8000... connected.
   HTTP request sent, awaiting response... No data received.
   Giving up.

If you use `pytest`_, you can also take advantage of poorconn fixtures in :mod:`poorconn.pytest_plugin`. The following
example gets you started with testing against a slow HTTP server:

.. code-block:: python

   pytest_plugins = ('poorconn',)

   from pathlib import Path
   import time
   import requests
   import pytest

   @pytest.mark.poorconn_http_server_config(t=2, length=1024)
   def test_slow_http_server(poorconn_http_server, tmp_path):
       "Test GETing from a slow local http server that delays 2 seconds to send every 1024 bytes."
       (tmp_path / 'index.txt').write_bytes(b'h' * 1024)
       starting_time = time.time()
       # Replace the following line with the program you want to test
       content = requests.get(f'{poorconn_http_server.url}/index.txt').content
       ending_time = time.time()
       assert ending_time - starting_time > 2

.. readme-misc

Bug Reports and Feature Requests
--------------------------------

Please open a ticket on the `GitLab Issue Tracker <https://gitlab.com/xuhdev/poorconn/-/issues>`__.

Contributing
------------

Contributions are welcome! To get started, check out :doc:`CONTRIBUTING`.

Copyright and License
---------------------

Copyright (C) 2020--2021 Hong Xu <hong@topbug.net>

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General
Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any
later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
details.

You should have received a copy of the GNU Lesser General Public License along with this program. If not, see
<https://www.gnu.org/licenses/>.

.. _pytest: https://www.pytest.org


