From e8712184093a6b40f8a722930791601917c1de7c Mon Sep 17 00:00:00 2001 From: Sara Date: Sun, 20 Oct 2024 14:19:58 +1100 Subject: [PATCH] Improve docs build and fix warnings (#150) --- .github/workflows/ci_cd.yml | 22 ++++++++++++ README.rst | 2 +- docs/api.rst | 69 ++----------------------------------- docs/conf.py | 8 ++--- docs/faq.rst | 14 ++++---- docs/how_it_works.rst | 18 +++++----- docs/install.rst | 6 ++-- pyproject.toml | 12 +++---- src/pook/request.py | 20 +++++------ src/pook/response.py | 8 +---- 10 files changed, 65 insertions(+), 114 deletions(-) diff --git a/.github/workflows/ci_cd.yml b/.github/workflows/ci_cd.yml index 7f96666..18eafb3 100644 --- a/.github/workflows/ci_cd.yml +++ b/.github/workflows/ci_cd.yml @@ -34,6 +34,28 @@ jobs: - name: Lint run: hatch run lint + docs: + name: build docs + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: '3.12' + cache: 'pip' + + - name: Install hatch + run: pipx install hatch + + - name: Build docs + run: hatch run docs:build --fail-on-warning + build: name: build runs-on: ubuntu-latest diff --git a/README.rst b/README.rst index 31c8541..c0393ab 100644 --- a/README.rst +++ b/README.rst @@ -61,7 +61,7 @@ Using ``pip`` package manager (requires pip 1.8+): pip install --upgrade pook -Or install the latest sources from Github: +Or install the latest sources from GitHub: .. code:: bash diff --git a/docs/api.rst b/docs/api.rst index 33bc414..be06a14 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -3,51 +3,13 @@ API Documentation ================= + Core API -------- -.. toctree:: - - pook.activate - pook.on - pook.disable - pook.off - pook.reset - pook.engine - pook.use - pook.context - pook.enable_network - pook.disable_network - pook.use_network - pook.use_network_filter - pook.flush_network_filters - pook.mock - pook.get - pook.put - pook.delete - pook.head - pook.patch - pook.options - pook.pending - pook.ispending - pook.pending_mocks - pook.unmatched_requests - pook.unmatched - pook.isunmatched - pook.isactive - pook.isdone - pook.regex - - pook.Mock - pook.Engine - pook.Request - pook.Response - pook.MockEngine - pook.MatcherEngine - - .. automodule:: pook :members: + :member-order: bysource :undoc-members: :show-inheritance: @@ -55,23 +17,6 @@ Core API Matchers API ------------ -.. toctree:: - - pook.matchers.init - pook.matchers.add - pook.matchers.get - pook.matchers.BaseMatcher - pook.matchers.MethodMatcher - pook.matchers.URLMatcher - pook.matchers.HeadersMatcher - pook.matchers.PathMatcher - pook.matchers.BodyMatcher - pook.matchers.XMLMatcher - pook.matchers.JSONMatcher - pook.matchers.JSONSchemaMatcher - pook.matchers.QueryMatcher - - .. automodule:: pook.matchers :members: :undoc-members: @@ -81,16 +26,8 @@ Matchers API Interceptors API ---------------- -.. toctree:: - - pook.interceptors.add - pook.interceptors.get - pook.interceptors.BaseInterceptor - pook.interceptors.Urllib3Interceptor - pook.interceptors.AIOHTTPInterceptor - pook.interceptors.HTTPClientInterceptor - .. automodule:: pook.interceptors :members: :undoc-members: :show-inheritance: + :exclude-members: activate, disable diff --git a/docs/conf.py b/docs/conf.py index 7597f84..6d5f60c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,7 +22,6 @@ sys.path.insert(0, os.path.abspath("..")) import pook # noqa -import sphinx_rtd_theme # -- General configuration ------------------------------------------------ @@ -130,9 +129,8 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -# html_theme = 'alabaster' html_theme = "sphinx_rtd_theme" -html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +# html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -166,7 +164,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ["_static"] +# html_static_path = ["_static"] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied @@ -350,4 +348,4 @@ # texinfo_no_detailmenu = False # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {"http://docs.python.org/": None} +# intersphinx_mapping = {"http://docs.python.org/": None} diff --git a/docs/faq.rst b/docs/faq.rst index 65c373a..de310b0 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -24,15 +24,15 @@ Does ``pook`` mock out all the outgoing HTTP traffic from my app? Yes, that's the default behaviour: any outgoing HTTP traffic across the supported HTTP clients will be intercepted by ``pook``. -In case that an outgoing traffic does not match any mock expectation, an exception error +In case that an outgoing request does not match any mock expectation, an exception error will be raised, telling you no mock was matched in order to review or fix your code accordingly. -You can for sure change this behaviour and don't raise any exception if no mock definition can be matched. +You can change this behaviour and don't raise any exception if no mock definition can be matched. -You can change this enabling the real networking mode via ``pook.enable_network()``. +You can change this enabling the real networking mode via :func:`pook.enable_network`. -Can I use ``pook`` in a non testing environment? +Can I use ``pook`` in a non-testing environment? ------------------------------------------------ Absolutely. ``pook`` is testing environment agnostic. @@ -49,17 +49,17 @@ Can I use ``pook`` with a custom HTTP traffic mock interceptor engine? Yes, you can. ``pook`` is very modular and open for extensibility. You can programmatically define the HTTP traffic mock engine you want to use via -``pook.set_mock_engine(engine)``. This will replace the built-in one. +:func:`pook.set_mock_engine`. This will replace the built-in one. This can be particularly useful if you are already using another HTTP mocking engine that satisfy your needs, but you want to take benefit of ``pook`` features, versatility and simple to use expressive API. -For mock engine implementation details, see ``pook.MockEngine`` API documentation. +For mock engine implementation details, see :any:`pook.MockEngine` API documentation. Can I use ``pook`` with any test framework? ------------------------------------------- -Yes. ``pook`` is test framework agnostic. +Yes. ``pook`` is framework-agnostic. You can use it within ``unittest``, ``pytest`` or others. diff --git a/docs/how_it_works.rst b/docs/how_it_works.rst index 518c7e5..5af98e4 100644 --- a/docs/how_it_works.rst +++ b/docs/how_it_works.rst @@ -5,12 +5,12 @@ HTTP traffic interception ------------------------- In a nutshell, ``pook`` uses ``unittest.mock`` standard Python package in order -to patch external library objects, allowing ``pook`` HTTP interceptor adapter to patch any third-party packages +to patch external library objects, allowing ``pook`` HTTP interceptor adaptor to patch any third-party packages and intercept specific function calls. ``pook`` entirely relies on this interception strategy, therefore in the meantime ``pook`` is active, any outgoing HTTP traffic intercepted by the supported HTTP clients won't imply any real TCP networking, -except if you enabled the real networking mode via ``pook.enable_network()``, which in +except if you enabled the real networking mode via :func:`pook.enable_network`, which in that case real network traffic can be established. Worth clarifying that ``pook`` only works at Python programmatic runtime level. @@ -33,16 +33,16 @@ will be ignored. Once the first one expires, the subsequent mock definition in t Real networking mode -------------------- -By default real networking mode is disabled. -This basically means that real networking will not happen unless you explicitely enable it. +By default, real networking mode is disabled. +This basically means that real networking will not happen unless you explicitly enable it. This behaviour has been adopted to improve predictability, control and mitigate developers fear between behaviour boundaries and expectations. -``pook`` will prevent you to communicate with real HTTP servers unless you enable it via: ``pook.enable_network()``. +``pook`` will prevent you to communicate with real HTTP servers unless you enable it via: :func:`pook.enable_network`. Also, you can partially restrict the real networking by filtering only certain hosts. -You can do that via ``pook.use_network_filter(filter_fn)``. +You can do that via :func:`pook.use_network_filter`. Volatile vs Persistent mocks @@ -53,7 +53,7 @@ and therefore consumed, it will be flushed. You can modify this behaviour via: -Explicitly definining the TTL of each mock, so effectively the number of times the mock can be matched and consumed: +Explicitly defining the TTL of each mock, so effectively the number of times the mock can be matched and consumed: .. code:: python @@ -64,11 +64,11 @@ Explicitly definining the TTL of each mock, so effectively the number of times t pook.get('server.com/api', times=5) -Explicitly definining a persistent mock: +Explicitly defining a persistent mock: .. code:: python - # Make a mock definition persistent, so it won't be never flushed + # Make a mock definition persistent, so it won't ever be flushed pook.get('server.com/api').persist() # The above is equivalent to diff --git a/docs/install.rst b/docs/install.rst index 0ca9017..4569462 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -4,18 +4,18 @@ Installation PyPI ---- -You can install the last stable release of Expects from PyPI using pip or easy_install:: +You can install the last stable release of pook from PyPI using pip:: $ pip install pook GitHub ------ -Or install the latest sources from Github:: +Or install the latest sources from GitHub:: $ pip install -e git+git://github.com/h2non/pook.git#egg=pook -Also you can download a source code package from `Github `_ and install it using setuptools:: +You can also download a source code package from `GitHub `_ and install it using setuptools:: $ tar xvf pook-{version}.tar.gz $ cd pook diff --git a/pyproject.toml b/pyproject.toml index ec0752f..9fc07ef 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -52,7 +52,7 @@ packages = ["src/pook"] [tool.hatch.envs.default] python = "3.13" -extra-dependencies = [ +dependencies = [ "pre-commit~=4.0", "mypy>=1.11.2", @@ -86,14 +86,14 @@ types = "mypy --install-types --non-interactive src/pook/interceptors {args}" [tool.hatch.envs.docs] extra-dependencies = [ - "Sphinx~=7.2.6 ", - "sphinx-rtd-theme~=2.0.0", + "sphinx==8.1.3", + "sphinx-autobuild==2024.10.3", + "sphinx-rtd-theme==3.0.1", ] [tool.hatch.envs.docs.scripts] -apidocs = "sphinx-apidoc -f --follow-links -H 'API documentation' -o docs/source src/pook" -htmldocs = "rm -rf docs/_build && sphinx-build -b html -d docs/_build/doctrees ./docs docs/_build/html" -build = "hatch run apidocs; hatch run htmldocs" +preview = "sphinx-autobuild docs docs/_build/html {args}" +build = "sphinx-build -b html docs docs/_build/html {args}" [tool.hatch.envs.test] [[tool.hatch.envs.test.matrix]] diff --git a/src/pook/request.py b/src/pook/request.py index 6868994..76ec43f 100644 --- a/src/pook/request.py +++ b/src/pook/request.py @@ -20,20 +20,13 @@ class Request: body (bytes|regex): request body payload to match. json (str|dict|list): JSON payload body structure to match. xml (str): XML payload data structure to match. - - Attributes: - method (str): HTTP method to match. Defaults to ``GET``. - url (str): URL request to intercept and match. - headers (dict): HTTP headers to match. - query (dict): URL query params to match. Complementely to URL - defined query params. - body (bytes|regex): request body payload to match. - json (str|dict|list): JSON payload body structure to match. - xml (str): XML payload data structure to match. """ # Store keys keys = ("method", "headers", "body", "url", "query", "xml", "json") + """ + :meta private: + """ def __init__(self, method="GET", **kw): self._url = None @@ -47,6 +40,7 @@ def __init__(self, method="GET", **kw): @property def method(self): + """HTTP method to match. Defaults to ``GET``.""" return self._method @method.setter @@ -55,6 +49,7 @@ def method(self, method): @property def headers(self): + """HTTP headers to match.""" return self._headers @headers.setter @@ -75,6 +70,7 @@ def extra(self, extra): @property def url(self): + """URL request to intercept and match.""" return self._url @url.setter @@ -98,6 +94,7 @@ def rawurl(self): @property def query(self): + """URL query params to match. Complementary to URL defined query params.""" return self._query @query.setter @@ -106,6 +103,7 @@ def query(self, params): @property def body(self): + """request body payload to match.""" return self._body @body.setter @@ -117,6 +115,7 @@ def body(self, body): @property def json(self): + """JSON payload body structure to match.""" return _json.loads(self.body.decode("utf-8")) @json.setter @@ -128,6 +127,7 @@ def json(self, data): @property def xml(self): + """XML payload data structure to match.""" return self.body.decode("utf-8") @xml.setter diff --git a/src/pook/response.py b/src/pook/response.py index 4143307..b07b75f 100644 --- a/src/pook/response.py +++ b/src/pook/response.py @@ -19,9 +19,6 @@ class Response: xml (str): HTTP response XML body. type (str): HTTP response content MIME type. file (str): file path to HTTP body response. - - Attributes: - mock (pook.Mock): reference to mock instance. """ _KEY_ORDER = ( @@ -227,15 +224,12 @@ def file(self, path): @property def mock(self): """ - Getter accessor for `mock` attribute. + Reference to mock instance. """ return self._mock @mock.setter def mock(self, mock): - """ - Setter for ``mock`` attribute. - """ self._mock = mock def __repr__(self):