diff --git a/.gitpod.yml b/.gitpod.yml new file mode 100644 index 0000000..8c924e6 --- /dev/null +++ b/.gitpod.yml @@ -0,0 +1,23 @@ +# See https://www.gitpod.io/docs/references/gitpod-yml for full reference + +tasks: + - name: Setup Development and run Tests + + init: | + # Upgrade pyenv itself + pyenv update + + export PY_VERSIONS="3.7 3.8 3.9 3.10" + + # Install all supported Python versions + for py in $PY_VERSIONS; + do pyenv install "$py":latest --skip-existing ; + done + + # Make versions available via $PATH, exclude GitPod default + pyenv global $(pyenv versions --bare | grep -v 3.8.13) + + # Install `tox` test orchestrator + pip install tox + + command: tox diff --git a/CHANGES.rst b/CHANGES.rst index f401997..231ba96 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,6 +1,17 @@ Changes ======= +36.0 (2022-07-19) +----------------- + +* Enable gitpod development (#238) +* Allow rst admonitions to render (#242) +* Add badges to README (#243) +* Update codebase for modern Python (#244) +* Fix table cell spans (#245) +* Allow ``math`` directive in rst (#246) +* Preserve ``lang`` attribute in ``pre`` (#247) + 35.0 (2022-04-19) ----------------- diff --git a/README.rst b/README.rst index 1dde903..348e82b 100644 --- a/README.rst +++ b/README.rst @@ -1,6 +1,12 @@ Readme Renderer =============== +.. image:: https://badge.fury.io/py/readme-renderer.svg + :target: https://badge.fury.io/py/readme-renderer + +.. image:: https://github.com/pypa/readme_renderer/actions/workflows/ci.yml/badge.svg + :target: https://github.com/pypa/readme_renderer/actions/workflows/ci.yml + Readme Renderer is a library that will safely render arbitrary ``README`` files into HTML. It is designed to be used in Warehouse_ to render the ``long_description`` for packages. It can handle Markdown, diff --git a/pyproject.toml b/pyproject.toml index 22f34d0..7ed9175 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -2,6 +2,10 @@ requires = ["setuptools>=40.8.0", "wheel", "bleach>=2.1.0", "docutils>=0.13.1", "Pygments>=2.5.1"] build-backend = "setuptools.build_meta:__legacy__" +# TODO: Remove when https://github.com/mgedmin/check-manifest/pull/155 released +[tool.check-manifest] +ignore = [".gitpod.yml"] + [tool.mypy] strict = true warn_unused_configs = true diff --git a/readme_renderer/__about__.py b/readme_renderer/__about__.py index b1e67d4..c862047 100644 --- a/readme_renderer/__about__.py +++ b/readme_renderer/__about__.py @@ -11,7 +11,6 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -from __future__ import absolute_import, division, print_function __all__ = [ "__title__", @@ -30,7 +29,7 @@ ) __uri__ = "https://github.com/pypa/readme_renderer" -__version__ = "35.0" +__version__ = "36.0" __author__ = "The Python Packaging Authority" __email__ = "admin@mail.pypi.org" diff --git a/readme_renderer/__init__.py b/readme_renderer/__init__.py index c3eb860..cdec169 100644 --- a/readme_renderer/__init__.py +++ b/readme_renderer/__init__.py @@ -11,4 +11,3 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -from __future__ import absolute_import, division, print_function diff --git a/readme_renderer/__main__.py b/readme_renderer/__main__.py index 527d96d..74983fc 100644 --- a/readme_renderer/__main__.py +++ b/readme_renderer/__main__.py @@ -1,4 +1,3 @@ -from __future__ import absolute_import, print_function import argparse from readme_renderer.rst import render import sys diff --git a/readme_renderer/clean.py b/readme_renderer/clean.py index 042883c..6c89fd5 100644 --- a/readme_renderer/clean.py +++ b/readme_renderer/clean.py @@ -11,7 +11,6 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -from __future__ import absolute_import, division, print_function import functools from typing import Any, Dict, Iterator, List, Optional @@ -46,8 +45,8 @@ "img": ["src", "width", "height", "alt", "align", "class"], "span": ["class"], "th": ["align"], - "td": ["align"], - "div": ["align"], + "td": ["align", "colspan", "rowspan"], + "div": ["align", "class"], "h1": ["align"], "h2": ["align"], "h3": ["align"], @@ -55,7 +54,8 @@ "h5": ["align"], "h6": ["align"], "code": ["class"], - "p": ["align"], + "p": ["align", "class"], + "pre": ["lang"], "ol": ["start"], "input": ["type", "checked", "disabled"], } diff --git a/readme_renderer/markdown.py b/readme_renderer/markdown.py index d5d3ccb..6e71a43 100644 --- a/readme_renderer/markdown.py +++ b/readme_renderer/markdown.py @@ -11,7 +11,6 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -from __future__ import absolute_import, division, print_function import re import warnings @@ -117,7 +116,7 @@ def replacer(match: Match[Any]) -> str: highlighted = pygments.highlight(code, lexer, formatter) - return '
{}
'.format(highlighted) + return f'
{highlighted}
' result = code_expr.sub(replacer, html) diff --git a/readme_renderer/rst.py b/readme_renderer/rst.py index 7bfaebc..fdc4e82 100644 --- a/readme_renderer/rst.py +++ b/readme_renderer/rst.py @@ -11,7 +11,6 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -from __future__ import absolute_import, division, print_function import io from typing import Any, Dict, IO, Optional, Union @@ -43,7 +42,7 @@ def emptytag( if "height" in node: attributes["height"] = node["height"] - return super(ReadMeHTMLTranslator, self).emptytag( + return super().emptytag( node, tagname, suffix, **attributes ) @@ -77,7 +76,8 @@ def emptytag( # Output math blocks as LaTeX that can be interpreted by MathJax for # a prettier display of Math formulas. - "math_output": "MathJax", + # Pass a dummy path to supress docutils warning and emit HTML. + "math_output": "MathJax /dummy.js", # Disable raw html as enabling it is a security risk, we do not want # people to be able to include any old HTML in the final output. diff --git a/readme_renderer/txt.py b/readme_renderer/txt.py index 13dc38a..5af4805 100644 --- a/readme_renderer/txt.py +++ b/readme_renderer/txt.py @@ -11,20 +11,12 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -from __future__ import absolute_import, division, print_function -import sys from typing import Any, Optional from .clean import clean -if sys.version_info >= (3,): - from html import escape as html_escape -else: - from cgi import escape - - def html_escape(s): - return escape(s, quote=True).replace("'", ''') +from html import escape as html_escape def render(raw: str, **kwargs: Any) -> Optional[str]: diff --git a/setup.cfg b/setup.cfg index 0c9e0fc..8183238 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,2 +1,2 @@ [metadata] -license_file = LICENSE +license_files = LICENSE diff --git a/setup.py b/setup.py index ec2e685..9b787b4 100644 --- a/setup.py +++ b/setup.py @@ -11,19 +11,18 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -from __future__ import absolute_import, division, print_function -import os +import pathlib import setuptools -base_dir = os.path.dirname(__file__) +base_dir = pathlib.Path(__file__).parent -with open(os.path.join(base_dir, "readme_renderer", "__about__.py")) as f: +with open(base_dir.joinpath("readme_renderer", "__about__.py")) as f: about = {} exec(f.read(), about) -with open(os.path.join(base_dir, "README.rst")) as f: +with open(base_dir.joinpath("README.rst")) as f: long_description = f.read() diff --git a/tests/fixtures/test_CommonMark_008.html b/tests/fixtures/test_CommonMark_008.html index 3126beb..b941909 100644 --- a/tests/fixtures/test_CommonMark_008.html +++ b/tests/fixtures/test_CommonMark_008.html @@ -1,5 +1,5 @@

Here is some Python code for a Dog:

-
class Dog(Animal):
+
class Dog(Animal):
     def __init__(self, name):
         self.name = name
 
@@ -9,7 +9,7 @@
 dog = Dog('Fido')
 

 
and then here is some bash:

-
if [ "$1" = "--help" ]; then
+
if [ "$1" = "--help" ]; then
     echo "OK"
 fi
 

diff --git a/tests/fixtures/test_GFM_doublequotes.html b/tests/fixtures/test_GFM_doublequotes.html
index ff2c748..546fd39 100644
--- a/tests/fixtures/test_GFM_doublequotes.html
+++ b/tests/fixtures/test_GFM_doublequotes.html
@@ -1,11 +1,11 @@
 
This is normal text.

 
This is code text.
 

-
def this_is_python():
+
def this_is_python():
     """This is a docstring."""
     pass
 

-
func ThisIsGo(){
+
func ThisIsGo(){
     return
 }
 

diff --git a/tests/fixtures/test_GFM_highlight.html b/tests/fixtures/test_GFM_highlight.html
index 45a1cab..4094325 100644
--- a/tests/fixtures/test_GFM_highlight.html
+++ b/tests/fixtures/test_GFM_highlight.html
@@ -1,10 +1,12 @@
 
This is normal text.

 
This is code text.
 

-
def this_is_python():
+
def this_is_python():
     pass
 

-
func ThisIsGo(){
+
func ThisIsGo(){
     return
 }
 

+
An unknown code fence block
+

diff --git a/tests/fixtures/test_GFM_highlight.md b/tests/fixtures/test_GFM_highlight.md
index 3829fcf..2b0cba6 100644
--- a/tests/fixtures/test_GFM_highlight.md
+++ b/tests/fixtures/test_GFM_highlight.md
@@ -14,3 +14,7 @@ func ThisIsGo(){
     return
 }
 ```
+
+```abc
+An unknown code fence block
+```
diff --git a/tests/fixtures/test_GFM_highlight_default_py.html b/tests/fixtures/test_GFM_highlight_default_py.html
index a995f63..d85d6ce 100644
--- a/tests/fixtures/test_GFM_highlight_default_py.html
+++ b/tests/fixtures/test_GFM_highlight_default_py.html
@@ -1,4 +1,4 @@
-
async def this_is_python():
+
async def this_is_python():
     pass
 
 print(await this_is_python())
diff --git a/tests/fixtures/test_GFM_malicious_pre.html b/tests/fixtures/test_GFM_malicious_pre.html
index a8d2378..7194eee 100644
--- a/tests/fixtures/test_GFM_malicious_pre.html
+++ b/tests/fixtures/test_GFM_malicious_pre.html
@@ -1,5 +1,5 @@
 
This is normal text.

-
def this_is_python():
+
def this_is_python():
     """This is a docstring."""
     pass
 <script type="text/javascript">alert('I am evil.');</script>
diff --git a/tests/fixtures/test_rst_003.html b/tests/fixtures/test_rst_003.html
index e135ee9..17cefc9 100644
--- a/tests/fixtures/test_rst_003.html
+++ b/tests/fixtures/test_rst_003.html
@@ -1,8 +1,8 @@
-

+

 
Required packages

 
To run the PyPI software, you need Python 2.5+ and PostgreSQL

 

-

+

 
Quick development setup

 
Make sure you are sitting

 

diff --git a/tests/fixtures/test_rst_admonitions.html b/tests/fixtures/test_rst_admonitions.html
new file mode 100644
index 0000000..f35589f
--- /dev/null
+++ b/tests/fixtures/test_rst_admonitions.html
@@ -0,0 +1,13 @@
+

+
!DANGER!

+
Will Robinson

+

+

+
Note

+
F Sharp is a note, right?

+

+

+
See also

+
A customized admonition.
+Read more at docutils

+

diff --git a/tests/fixtures/test_rst_admonitions.rst b/tests/fixtures/test_rst_admonitions.rst
new file mode 100644
index 0000000..9de1da7
--- /dev/null
+++ b/tests/fixtures/test_rst_admonitions.rst
@@ -0,0 +1,11 @@
+.. danger:: Will Robinson
+
+.. note::
+
+   F Sharp is a note, right?
+
+
+.. admonition:: See also
+
+   A customized admonition.
+   Read more at `docutils `_
diff --git a/tests/fixtures/test_rst_docinfo.html b/tests/fixtures/test_rst_docinfo.html
index 7718e63..9a34ce9 100644
--- a/tests/fixtures/test_rst_docinfo.html
+++ b/tests/fixtures/test_rst_docinfo.html
@@ -14,6 +14,6 @@
 © 2017, 2018 Lele Gaifax
 
 
-

+

 
pg_query

 

diff --git a/tests/fixtures/test_rst_linkify.html b/tests/fixtures/test_rst_linkify.html
index b1864dd..e924e12 100644
--- a/tests/fixtures/test_rst_linkify.html
+++ b/tests/fixtures/test_rst_linkify.html
@@ -7,7 +7,7 @@
 
It requires a spatial databases compatible with GeoDjango.  PostgreSQL 9.x
 and PostGIS 2.x are recommended for development and production, since these
 support all the GeoDjango features.

-

+

 
Status

 
multigtfs is ready for your GTFS project.

 
Point releases (0.4.1 to 0.4.2) should be safe, only adding features or fixing
@@ -25,11 +25,11 @@ 
Status

 archive feeds).  If you find a feed that doesn’t work, file a bug!

 
See the issues list for more details on bugs and feature requests.

 

-

+

 
Example project

 
Check out the example project.

 

-

+

 
Development

 diff --git a/tests/fixtures/test_rst_math.html b/tests/fixtures/test_rst_math.html
new file mode 100644
index 0000000..763c958
--- /dev/null
+++ b/tests/fixtures/test_rst_math.html
@@ -0,0 +1,8 @@
+
A math directive:

+

+\begin{equation*}
+\alpha _t(i) = P(O_1, O_2, \ldots  O_t, q_t = S_i \lambda )
+\end{equation*}
+

+
A :math: role:

+
The area of a circle is \(A_\text{c} = (\pi/4) d^2\).

diff --git a/tests/fixtures/test_rst_math.rst b/tests/fixtures/test_rst_math.rst
new file mode 100644
index 0000000..b4e6db7
--- /dev/null
+++ b/tests/fixtures/test_rst_math.rst
@@ -0,0 +1,14 @@
+.. Sample from https://docutils.sourceforge.io/docs/ref/rst/directives.html#math
+
+A ``math`` directive:
+
+.. math::
+
+  α_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ)
+
+
+.. Sample from https://docutils.sourceforge.io/docs/ref/rst/roles.html#math
+
+A ``:math:`` role:
+
+The area of a circle is :math:`A_\text{c} = (\pi/4) d^2`.
diff --git a/tests/fixtures/test_rst_tables.html b/tests/fixtures/test_rst_tables.html
new file mode 100644
index 0000000..2e2a984
--- /dev/null
+++ b/tests/fixtures/test_rst_tables.html
@@ -0,0 +1,62 @@
+

 


++++++
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+






Header row, column 1
+(header rows optional)Header 2Header 3Header 4
body row 1, column 1column 2column 3column 4
body row 2Cells may span columns.
body row 3Cells may
+span rows.
    
+
  • Table cells
    • 
+
  • contain
    • 
+
  • body elements.
    • 
+

+
body row 4

+
++++
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+




title1title2
col1col2
mutirowcell1
cell2
singlerowcell3

diff --git a/tests/fixtures/test_rst_tables.rst b/tests/fixtures/test_rst_tables.rst
new file mode 100644
index 0000000..52ceaa2
--- /dev/null
+++ b/tests/fixtures/test_rst_tables.rst
@@ -0,0 +1,28 @@
+.. Example from https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#tables
+
++------------------------+------------+----------+----------+
+| Header row, column 1   | Header 2   | Header 3 | Header 4 |
+| (header rows optional) |            |          |          |
++========================+============+==========+==========+
+| body row 1, column 1   | column 2   | column 3 | column 4 |
++------------------------+------------+----------+----------+
+| body row 2             | Cells may span columns.          |
++------------------------+------------+---------------------+
+| body row 3             | Cells may  | - Table cells       |
++------------------------+ span rows. | - contain           |
+| body row 4             |            | - body elements.    |
++------------------------+------------+---------------------+
+
+.. Example from #182
+
++---------------+---------------+
+| title1        | title2        |
++===============+===============+
+| col1          | col2          |
++---------------+---------------+
+| mutirow       | cell1         |
+|               +---------------+
+|               | cell2         |
++---------------+---------------+
+| singlerow     | cell3         |
++---------------+---------------+
diff --git a/tests/test_markdown.py b/tests/test_markdown.py
index 492bc81..8d529a7 100755
--- a/tests/test_markdown.py
+++ b/tests/test_markdown.py
@@ -1,36 +1,25 @@
-import io
-import glob
-import os
+from pathlib import Path
 
 import pytest
 
 from readme_renderer.markdown import render, variants
 
 
-MD_FIXTURES = [
-    (fn, os.path.splitext(fn)[0] + ".html", variant)
-    for variant in variants
-    for fn in glob.iglob(
-        os.path.join(
-            os.path.dirname(__file__),
-            "fixtures",
-            "test_" + variant + "*.md"
-        )
-    )
-]
-
-
 @pytest.mark.parametrize(
     ("md_filename", "html_filename", "variant"),
-    MD_FIXTURES,
+    [
+        (pytest.param(fn, fn.with_suffix(".html"), variant, id=fn.name))
+        for variant in variants
+        for fn in Path(__file__).parent.glob(f"fixtures/test_{variant}*.md")
+    ],
 )
 def test_md_fixtures(md_filename, html_filename, variant):
     # Get our Markup
-    with io.open(md_filename, encoding='utf-8') as f:
+    with open(md_filename, encoding='utf-8') as f:
         md_markup = f.read()
 
     # Get our expected
-    with io.open(html_filename, encoding="utf-8") as f:
+    with open(html_filename, encoding="utf-8") as f:
         expected = f.read()
 
     assert render(md_markup, variant=variant) == expected
diff --git a/tests/test_rst.py b/tests/test_rst.py
index 4e04c17..f1caf8d 100755
--- a/tests/test_rst.py
+++ b/tests/test_rst.py
@@ -1,6 +1,5 @@
 import io
-import glob
-import os.path
+from pathlib import Path
 
 import pytest
 
@@ -10,19 +9,17 @@
 @pytest.mark.parametrize(
     ("rst_filename", "html_filename"),
     [
-        (fn, os.path.splitext(fn)[0] + ".html")
-        for fn in glob.glob(
-            os.path.join(os.path.dirname(__file__), "fixtures", "test_*.rst")
-        )
+        (pytest.param(fn, fn.with_suffix(".html"), id=fn.name))
+        for fn in Path(__file__).parent.glob("fixtures/test_*.rst")
     ],
 )
 def test_rst_fixtures(rst_filename, html_filename):
     # Get our Markup
-    with io.open(rst_filename, encoding='utf-8') as f:
+    with open(rst_filename, encoding='utf-8') as f:
         rst_markup = f.read()
 
     # Get our expected
-    with io.open(html_filename, encoding="utf-8") as f:
+    with open(html_filename, encoding="utf-8") as f:
         expected = f.read()
 
     out = render(rst_markup)
diff --git a/tests/test_txt.py b/tests/test_txt.py
index b3a5274..9f4f1ac 100644
--- a/tests/test_txt.py
+++ b/tests/test_txt.py
@@ -1,6 +1,4 @@
-import io
-import glob
-import os.path
+from pathlib import Path
 
 import pytest
 
@@ -10,19 +8,17 @@
 @pytest.mark.parametrize(
     ("txt_filename", "html_filename"),
     [
-        (fn, os.path.splitext(fn)[0] + ".html")
-        for fn in glob.glob(
-            os.path.join(os.path.dirname(__file__), "fixtures", "test_*.txt")
-        )
+        (pytest.param(fn, fn.with_suffix(".html"), id=fn.name))
+        for fn in Path(__file__).parent.glob("fixtures/test_*.txt")
     ],
 )
 def test_txt_fixtures(txt_filename, html_filename):
     # Get our Markup
-    with io.open(txt_filename, encoding='utf-8') as f:
+    with open(txt_filename, encoding='utf-8') as f:
         txt_markup = f.read()
 
     # Get our expected
-    with io.open(html_filename, encoding="utf-8") as f:
+    with open(html_filename, encoding="utf-8") as f:
         expected = f.read()
 
     out = render(txt_markup)