Merge pull request #8 from dapper91/dev

- refactoring done

Author: dapper91

.gitignore

@@ -128,5 +128,8 @@ dmypy.json
 # Pyre type checker
 .pyre/
 
+# IDE
+.idea
+
 # poetry
 poetry.lock

.readthedocs.yaml

@@ -0,0 +1,18 @@
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/source/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

CHANGELOG.rst

@@ -1,6 +1,12 @@
 Changelog
 =========
 
+0.3.0 (2023-08-10)
+------------------
+
+- refactoring done.
+
+
 0.2.0 (2023-04-19)
 ------------------
 

README.rst

@@ -17,218 +17,96 @@ generic-connection-pool
 .. image:: https://codecov.io/gh/dapper91/generic-connection-pool/branch/master/graph/badge.svg
     :target: https://codecov.io/gh/dapper91/generic-connection-pool
     :alt: Code coverage
+.. image:: https://readthedocs.org/projects/generic-connection-pool/badge/?version=stable&style=flat
+   :alt: ReadTheDocs status
+   :target: https://generic-connection-pool.readthedocs.io/en/stable/
 
 
 ``generic-connection-pool`` is a connection pool that can be used for TCP, http, database connections.
 
-Features:
+Features
+--------
 
 - **generic nature**: can be used for any connection you desire (TCP, http, database)
 - **runtime agnostic**: synchronous and asynchronous pool supported
 - **flexibility**: flexable connection retention and recycling policy
 - **fully-typed**: mypy type-checker compatible
 
 
-Installation
-------------
+Getting started
+---------------
 
-You can install generic-connection-pool with pip:
+Connection pool supports the following configurations:
 
-.. code-block:: console
+* **background_collector**: if ``True`` starts a background worker that disposes expired and idle connections
+  maintaining requested pool state. If ``False`` the connections will be disposed on each connection release.
+* **dispose_batch_size**: maximum number of expired and idle connections to be disposed on connection release
+  (if background collector is started the parameter is ignored).
+* **idle_timeout**: inactivity time (in seconds) after which an extra connection will be disposed
+  (a connection considered as extra if the number of endpoint connection exceeds ``min_idle``).
+* **max_lifetime**: number of seconds after which any connection will be disposed.
+* **min_idle**: minimum number of connections in each endpoint the pool tries to hold. Connections that exceed
+  that number will be considered as extra and disposed after ``idle_timeout`` seconds of inactivity.
+* **max_size**: maximum number of endpoint connections.
+* **total_max_size**: maximum number of all connections in the pool.
 
-    $ pip install generic-connection-pool
-
-
-Quickstart
-----------
-
-The following example illustrates how to create asynchronous ssl socket pool:
+The following example illustrates how to create https pool:
 
 .. code-block:: python
 
-    import asyncio
+    import socket
+    import ssl
+    import urllib.parse
+    from http.client import HTTPResponse
     from typing import Tuple
 
-    from generic_connection_pool.asyncio import ConnectionPool
-    from generic_connection_pool.contrib.socket_async import TcpStreamConnectionManager
+    from generic_connection_pool.contrib.socket import SslSocketConnectionManager
+    from generic_connection_pool.threading import ConnectionPool
 
     Hostname = str
     Port = int
     Endpoint = Tuple[Hostname, Port]
-    Connection = Tuple[asyncio.StreamReader, asyncio.StreamWriter]
-
-
-    async def main() -> None:
-        pool = ConnectionPool[Endpoint, Connection](
-            TcpStreamConnectionManager(ssl=True),
-            idle_timeout=30.0,
-            max_lifetime=600.0,
-            min_idle=3,
-            max_size=20,
-            total_max_size=100,
-            background_collector=True,
-        )
-
-        async with pool.connection(endpoint=('www.wikipedia.org', 443), timeout=5.0) as (reader, writer):
-            request = (
-                'GET / HTTP/1.0\n'
-                'Host: www.wikipedia.org\n'
-                '\n'
-                '\n'
-            )
-            writer.write(request.encode())
-            await writer.drain()
-            response = await reader.read()
-
-            print(response.decode())
-
-    asyncio.run(main())
-
-
-Configuration
--------------
-
-Synchronous and asynchronous pools supports the following parameters:
-
-* **connection_manager**: connection manager instance
-* **acquire_timeout**: connection acquiring default timeout
-* **dispose_batch_size**: number of connections to be disposed at once
-  (if background collector is started the parameter is ignored)
-* **dispose_timeout**: connection disposal timeout
-* **background_collector**: start worker that disposes timed-out connections in background maintain provided pool state
-  otherwise they will be disposed on each connection release
-* **idle_timeout**: number of seconds after which a connection will be closed respecting min_idle parameter
-  (the connection will be closed only if the connection number exceeds min_idle)
-* **max_lifetime**: number of seconds after which a connection will be closed (min_idle parameter will be ignored)
-* **min_idle**: minimum number of connections the pool tries to hold (for each endpoint)
-* **max_size**: maximum number of connections (for each endpoint)
-* **total_max_size**: maximum number of connections (for all endpoints)
-
-
-Generic nature
---------------
-
-Since the pool has generic nature is can be used for database connections as well:
-
-.. code-block:: python
-
-    import psycopg2.extensions
-
-    from generic_connection_pool.contrib.psycopg2 import DbConnectionManager
-    from generic_connection_pool.threding import ConnectionPool
-
-    Endpoint = str
-    Connection = psycopg2.extensions.connection
-
-
-    def main() -> None:
-        dsn_params = dict(dbname='postgres', user='postgres', password='secret')
+    Connection = socket.socket
 
-        pool = ConnectionPool[Endpoint, Connection](
-            DbConnectionManager(
-                dsn_params={
-                    'master': dict(dsn_params, host='db-master.local'),
-                    'replica-1': dict(dsn_params, host='db-replica-1.local'),
-                    'replica-2': dict(dsn_params, host='db-replica-2.local'),
-                },
-            ),
-            acquire_timeout=2.0,
-            idle_timeout=60.0,
-            max_lifetime=600.0,
-            min_idle=3,
-            max_size=10,
-            total_max_size=15,
-            background_collector=True,
-        )
 
-        with pool.connection(endpoint='master') as conn:
-            cur = conn.cursor()
-            cur.execute("SELECT * FROM pg_stats;")
-            print(cur.fetchone())
+    http_pool = ConnectionPool[Endpoint, Connection](
+        SslSocketConnectionManager(ssl.create_default_context()),
+        idle_timeout=30.0,
+        max_lifetime=600.0,
+        min_idle=3,
+        max_size=20,
+        total_max_size=100,
+        background_collector=True,
+    )
 
-        with pool.connection(endpoint='replica-1') as conn:
-            cur = conn.cursor()
-            cur.execute("SELECT * FROM pg_stats;")
-            print(cur.fetchone())
 
-        pool.close()
+    def fetch(url: str, timeout: float = 5.0) -> None:
+        url = urllib.parse.urlsplit(url)
+        port = url.port or 443 if url.scheme == 'https' else 80
 
+        with http_pool.connection(endpoint=(url.hostname, port), timeout=timeout) as sock:
+            request = (
+                'GET {path} HTTP/1.1\r\n'
+                'Host: {host}\r\n'
+                '\r\n'
+                '\r\n'
+            ).format(host=url.hostname, path=url.path)
 
-    main()
-
-
-Extendability
--------------
-
-If built-in connection managers are not suitable for your task the one can be easily created by yourself:
-
-.. code-block:: python
-
-    import socket
-    from ssl import SSLContext, SSLSocket
-    from typing import Optional, Tuple
-
-    from generic_connection_pool.threding import BaseConnectionManager, ConnectionPool
-
-    Hostname = str
-    Port = int
-    SslEndpoint = Tuple[Hostname, Port]
-    Connection = SSLSocket
-
-
-    class SslSocketConnectionManager(BaseConnectionManager[SslEndpoint, Connection]):
-        """
-        SSL socket connection manager.
-        """
-
-        def __init__(self, ssl: SSLContext):
-            self._ssl = ssl
-
-        def create(self, endpoint: SslEndpoint, timeout: Optional[float] = None) -> Connection:
-            hostname, port = endpoint
-
-            sock = self._ssl.wrap_socket(socket.socket(type=socket.SOCK_STREAM), server_hostname=hostname)
-            sock.settimeout(timeout)
-            sock.connect((hostname, port))
-
-            return sock
-
-        def dispose(self, endpoint: SslEndpoint, conn: Connection, timeout: Optional[float] = None) -> None:
-            conn.settimeout(timeout)
-            try:
-                conn.shutdown(socket.SHUT_RDWR)
-            except OSError:
-                pass
-
-            conn.close()
-
+            sock.write(request.encode())
 
-    def main() -> None:
-        pool = ConnectionPool[SslEndpoint, Connection](
-            SslSocketConnectionManager(ssl=SSLContext()),
-            idle_timeout=30.0,
-            max_lifetime=600.0,
-            min_idle=3,
-            max_size=20,
-            total_max_size=100,
-            background_collector=True,
-        )
+            response = HTTPResponse(sock)
+            response.begin()
+            status, body = response.getcode(), response.read(response.length)
 
-        with pool.connection(endpoint=('www.wikipedia.org', 443), timeout=5.0) as sock:
-            request = (
-                'GET / HTTP/1.0\n'
-                'Host: www.wikipedia.org\n'
-                '\n'
-                '\n'
-            )
-            sock.write(request.encode())
-            response = []
-            while chunk := sock.recv():
-                response.append(chunk)
+            print(status)
+            print(body)
 
-            print(b''.join(response).decode())
 
-        pool.close()
+    try:
+        fetch('https://en.wikipedia.org/wiki/HTTP')  # http connection is opened
+        fetch('https://en.wikipedia.org/wiki/Python_(programming_language)')  # http connection is reused
+    finally:
+        http_pool.close()
 
 
-    main()
+See `documentation <https://generic-connection-pool.readthedocs.io/en/latest/>`_ for more details.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd