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
Description: .. 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
        
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
