Skip to content

Commit b13a17d

Browse files
domdfcodingdomdfcoding
committed
Update docs.
1 parent 5ab6b79 commit b13a17d

File tree

8 files changed

+61
-68
lines changed

8 files changed

+61
-68
lines changed

‎coverage_pyver_pragma/grammar.py

Lines changed: 48 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,23 @@
22
#
33
# grammar.py
44
"""
5-
The expression grammar for ``coverage_pyver_pragma``.
6-
75
.. versionadded:: 0.2.0
86
9-
Each expression consists of one or more tags (``VERSION_TAG``, ``PLATFORM_TAG`` or ``IMPLEMENTATION_TAG``).
7+
As with ``coverage.py``, lines are marked with comments in the form::
8+
9+
# pragma: no cover
10+
11+
With ``coverage_pyver_pragma``, the comment may be followed with an expression enclosed in parentheses::
12+
13+
# pragma: no cover (<=py38 and !Windows)
14+
15+
Each expression consists of one or more tags
16+
(:py:data:`VERSION_TAG`, :py:data:`PLATFORM_TAG` or :py:data:`IMPLEMENTATION_TAG`).
1017
The tags can be joined with the keywords ``AND``, ``OR`` and ``NOT``, with the exclamation mark ``!`` implying ``NOT``.
1118
Parentheses can be used to group sub expressions.
19+
A series of tags without keywords in between them are evaluated with ``AND``.
1220
13-
``VERSION_TAG``
14-
-------------------
21+
.. py:data:: VERSION_TAG
1522
1623
A ``VERSION_TAG`` comprises an optional comparator (one of ``<=``, ``<``, ``>=``, ``>``),
1724
a version specifier in the form ``pyXX``, and an optional ``+`` to indicate ``>=``.
@@ -27,8 +34,7 @@
2734
py34+ # equivalent to >=py34
2835
2936
30-
``PLATFORM_TAG``
31-
-------------------
37+
.. py:data:: PLATFORM_TAG
3238
3339
A ``PLATFORM_TAG`` comprises a single word which will be compared (ignoring case)
3440
with the output of :func:`platform.system`.
@@ -45,8 +51,7 @@
4551
If the current platform cannot be determined all strings are treated as :py:obj:`True`.
4652
4753
48-
``IMPLEMENTATION_TAG``
49-
-----------------------
54+
.. py:data:: IMPLEMENTATION_TAG
5055
5156
An ``IMPLEMENTATION_TAG`` comprises a single word which will be compared (ignoring case)
5257
with the output of :func:`platform.python_implementation`.
@@ -63,10 +68,32 @@
6368
Examples
6469
-----------
6570
66-
.. parsed-literal::
71+
ignore if the Python version is less than or equal to 3.7::
72+
73+
# pragma: no cover (<=py37)
74+
75+
ignore if running on Python 3.9::
76+
77+
# pragma: no cover (py39)
78+
79+
Ignore if the Python version is greater than 3.6 and it's not running on PyPy::
80+
81+
# pragma: no cover (>py36 and !PyPy)
6782
68-
>py36 and !PyPy
69-
Windows and <py38
83+
Ignore if the Python version is less than 3.8 and it's running on Windows::
84+
85+
# pragma: no cover (Windows and <py38)
86+
87+
Ignore when not running on macOS (Darwin)::
88+
89+
# pragma: no cover (!Darwin)
90+
91+
Ignore when not running on CPython::
92+
93+
# pragma: no cover (!CPython)
94+
95+
API Reference
96+
----------------
7097
7198
"""
7299
#
@@ -106,6 +133,7 @@
106133
Literal,
107134
OneOrMore,
108135
Optional,
136+
ParserElement,
109137
ParseResults,
110138
Word,
111139
infixNotation,
@@ -200,8 +228,8 @@ class PlatformTag(str):
200228

201229
__slots__ = ()
202230

203-
def __new__(cls, token: ParseResults): # noqa: D102
204-
return super().__new__(cls, str(token["platform"]))
231+
def __new__(cls, tokens: ParseResults): # noqa: D102
232+
return super().__new__(cls, str(tokens["platform"]))
205233

206234
def __repr__(self) -> str: # pragma: no cover
207235
return f"<{self.__class__.__name__}({str(self)!r})>"
@@ -353,7 +381,7 @@ def __bool__(self):
353381

354382
ELEMENTS = VERSION_TAG | PLATFORM_TAG | IMPLEMENTATION_TAG
355383

356-
GRAMMAR = OneOrMore(
384+
GRAMMAR: ParserElement = OneOrMore(
357385
infixNotation(
358386
ELEMENTS,
359387
[
@@ -363,3 +391,8 @@ def __bool__(self):
363391
]
364392
)
365393
)
394+
"""
395+
The ``coverage_pyver_pragma`` expression grammar.
396+
397+
This can be used to parse an expression outside of the coverage context.
398+
"""

‎doc-source/api.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
=============
2+
Public API
3+
=============
4+
5+
.. automodule:: coverage_pyver_pragma

‎doc-source/conf.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@
6262
intersphinx_mapping = {
6363
"python": ("https://docs.python.org/3/", None),
6464
"sphinx": ("https://www.sphinx-doc.org/en/stable/", None),
65+
"pyparsing": ("https://pyparsing-docs.readthedocs.io/en/latest", None),
6566
}
6667

6768
html_theme = "domdf_sphinx_theme"

‎doc-source/docs.rst

Lines changed: 0 additions & 7 deletions
This file was deleted.

‎doc-source/index.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,7 @@ coverage_pyver_pragma
103103
:alt: GitHub top language
104104

105105
.. |commits-since| github-shield::
106-
:commits-since: v0.0.6
106+
:commits-since: v0.2.0
107107
:alt: GitHub commits since tagged version
108108

109109
.. |commits-latest| github-shield::
@@ -147,7 +147,7 @@ Installation
147147

148148
installation
149149
syntax
150-
docs
150+
api
151151

152152
.. toctree::
153153
:maxdepth: 3

‎doc-source/requirements.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
autodocsumm>=0.2.0
22
default-values>=0.4.2
3-
domdf-sphinx-theme>=0.3.0
43
extras-require>=0.2.0
4+
furo>=2020.11.19b18
55
seed-intersphinx-mapping>=0.3.1
66
sphinx<3.4.0,>=3.0.3
77
sphinx-copybutton>=0.2.12

‎doc-source/syntax.rst

Lines changed: 1 addition & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -2,46 +2,4 @@
22
Syntax
33
=========
44

5-
To ignore when running with versions of Python above, for instance, Python 3.6:
6-
7-
.. code-block:: python
8-
9-
# pragma: no cover (>py36)
10-
11-
You can also ignore for a specific version of Python:
12-
13-
.. code-block:: python
14-
15-
# pragma: no cover (py36)
16-
17-
Other examples:
18-
19-
.. code-block:: python
20-
21-
# pragma: no cover (<py38)
22-
# pragma: no cover (<=py38)
23-
# pragma: no cover (>=py38)
24-
# pragma: no cover (py38+)
25-
26-
27-
You can also exclude lines based on platform. For example, to exclude a line when the platform is not Windows:
28-
29-
.. code-block:: python
30-
31-
# pragma: no cover (!Windows)
32-
33-
You can also exclude lines based on Python implementation. For example, to exclude a line when the implementation is not CPython:
34-
35-
.. code-block:: python
36-
37-
# pragma: no cover (!CPython)
38-
39-
These can also be combined with the Python version:
40-
41-
.. code-block:: python
42-
43-
# pragma: no cover (<=py36 !Windows !CPython)
44-
45-
This will ignore coverage (or lack thereof) for the branch if all three conditions are satisfied
46-
(Python 3.6 or earlier AND not Windows AND not CPython).
47-
It is not currently possible to ignore a branch if EITHER condition is true.
5+
.. automodule:: coverage_pyver_pragma.grammar

‎repo_helper.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,3 +33,6 @@ sphinx_html_theme: domdf_sphinx_theme
3333
tox_unmanaged:
3434
- coverage:run
3535
- testenv:coverage
36+
37+
intersphinx_mapping:
38+
- "'pyparsing': ('https://pyparsing-docs.readthedocs.io/en/latest', None)"

0 commit comments

Comments
 (0)