Merge pull request #11 from domdfcoding/1.8.0-dev

Add new features for v1.9.0

Author: domdfcoding

.github/workflows/mypy.yml

@@ -0,0 +1,36 @@
+# This file is managed by 'repo_helper'. Don't edit it directly.
+---
+name: mypy
+
+on:
+  push:
+  pull_request:
+    branches: ["master"]
+
+jobs:
+  Run:
+    name: "mypy"
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+
+    steps:
+      - name: Checkout 🛎️
+        uses: "actions/checkout@v2"
+
+      - name: Setup Python 🐍
+        uses: "actions/setup-python@v2"
+        with:
+          python-version: "3.8"
+
+      - name: Install dependencies 🔧
+        run: |
+          python -VV
+          python -m site
+          python -m pip install --upgrade pip setuptools wheel
+          python -m pip install tox
+
+      - name: "Run mypy"
+        run: "python -m tox -e mypy"

.github/workflows/python_ci.yml

@@ -9,15 +9,19 @@ on:
 
 jobs:
   tests:
-    name: "Python ${{ matrix.python-version }}"
+    name: "Python ${{ matrix.config.python-version }}"
     runs-on: "windows-2019"
     env:
       USING_COVERAGE: '3.6,3.7,3.8,3.9'
 
     strategy:
       fail-fast: False
       matrix:
-        python-version: ["3.6","3.7","3.8","3.9"]
+        config:
+          - {python-version: "3.6", testenvs: "py36,build"}
+          - {python-version: "3.7", testenvs: "py37,build"}
+          - {python-version: "3.8", testenvs: "py38,build"}
+          - {python-version: "3.9", testenvs: "py39,build"}
 
     steps:
       - name: Checkout 🛎️
@@ -26,14 +30,14 @@ jobs:
       - name: Setup Python 🐍
         uses: "actions/setup-python@v2"
         with:
-          python-version: "${{ matrix.python-version }}"
+          python-version: "${{ matrix.config.python-version }}"
 
       - name: Install dependencies 🔧
         run: |
           python -VV
           python -m site
           python -m pip install --upgrade pip setuptools wheel
-          python -m pip install --upgrade tox tox-gh-actions virtualenv
+          python -m pip install --upgrade tox virtualenv
 
-      - name: "Run Tests for Python ${{ matrix.python-version }}"
-        run: "python -m tox"
+      - name: "Run Tests for Python ${{ matrix.config.python-version }}"
+        run: "python -m tox -e ${{ matrix.config.testenvs }}"

.github/workflows/python_ci_linux.yml

@@ -9,15 +9,20 @@ on:
 
 jobs:
   tests:
-    name: "Python ${{ matrix.python-version }}"
+    name: "Python ${{ matrix.config.python-version }}"
     runs-on: "ubuntu-18.04"
     env:
       USING_COVERAGE: '3.6,3.7,3.8,pypy3,3.9'
 
     strategy:
       fail-fast: False
       matrix:
-        python-version: ["3.6","3.7","3.8","pypy3","3.9"]
+        config:
+          - {python-version: "3.6", testenvs: "py36,build"}
+          - {python-version: "3.7", testenvs: "py37,build"}
+          - {python-version: "3.8", testenvs: "py38,build"}
+          - {python-version: "pypy3", testenvs: "pypy3,build"}
+          - {python-version: "3.9", testenvs: "py39,build"}
 
     steps:
       - name: Checkout 🛎️
@@ -26,24 +31,24 @@ jobs:
       - name: Setup Python 🐍
         uses: "actions/setup-python@v2"
         with:
-          python-version: "${{ matrix.python-version }}"
+          python-version: "${{ matrix.config.python-version }}"
 
       - name: Install dependencies 🔧
         run: |
           python -VV
           python -m site
           python -m pip install --upgrade pip setuptools wheel
-          python -m pip install --upgrade tox tox-gh-actions virtualenv
+          python -m pip install --upgrade tox virtualenv
           python -m pip install --upgrade coverage_pyver_pragma
 
-      - name: "Run Tests for Python ${{ matrix.python-version }}"
-        run: "python -m tox"
+      - name: "Run Tests for Python ${{ matrix.config.python-version }}"
+        run: "python -m tox -e ${{ matrix.config.testenvs }}"
 
 
       - name: "Upload Coverage"
         uses: actions/upload-artifact@v2
         with:
-          name: "coverage-${{ matrix.python-version }}"
+          name: "coverage-${{ matrix.config.python-version }}"
           path: .coverage
 
 

.github/workflows/python_ci_macos.yml

@@ -9,15 +9,20 @@ on:
 
 jobs:
   tests:
-    name: "Python ${{ matrix.python-version }}"
+    name: "Python ${{ matrix.config.python-version }}"
     runs-on: "macos-latest"
     env:
       USING_COVERAGE: '3.6,3.7,3.8,pypy3,3.9'
 
     strategy:
       fail-fast: False
       matrix:
-        python-version: ["3.6","3.7","3.8","pypy3","3.9"]
+        config:
+          - {python-version: "3.6", testenvs: "py36,build"}
+          - {python-version: "3.7", testenvs: "py37,build"}
+          - {python-version: "3.8", testenvs: "py38,build"}
+          - {python-version: "pypy3", testenvs: "pypy3,build"}
+          - {python-version: "3.9", testenvs: "py39,build"}
 
     steps:
       - name: Checkout 🛎️
@@ -26,14 +31,14 @@ jobs:
       - name: Setup Python 🐍
         uses: "actions/setup-python@v2"
         with:
-          python-version: "${{ matrix.python-version }}"
+          python-version: "${{ matrix.config.python-version }}"
 
       - name: Install dependencies 🔧
         run: |
           python -VV
           python -m site
           python -m pip install --upgrade pip setuptools wheel
-          python -m pip install --upgrade tox tox-gh-actions virtualenv
+          python -m pip install --upgrade tox virtualenv
 
-      - name: "Run Tests for Python ${{ matrix.python-version }}"
-        run: "python -m tox"
+      - name: "Run Tests for Python ${{ matrix.config.python-version }}"
+        run: "python -m tox -e ${{ matrix.config.testenvs }}"

domdf_python_tools/paths.py

@@ -41,6 +41,7 @@
 
 # stdlib
 import contextlib
+import gzip
 import json
 import os
 import pathlib
@@ -543,17 +544,20 @@ def dump_json(
 			encoding: Optional[str] = "UTF-8",
 			errors: Optional[str] = None,
 			json_library: JsonLibrary = json,  # type: ignore
+			*,
+			compress: bool = False,
 			**kwargs,
 			) -> None:
-		"""
+		r"""
 		Dump ``data`` to the file as JSON.
 
 		:param data: The object to serialise to JSON.
 		:param encoding: The encoding to write to the file in.
 		:param errors:
 		:param json_library: The JSON serialisation library to use.
 		:default json_library: :mod:`json`
-		:param kwargs: Keyword arguments to pass to the JSON serialisation function.
+		:param compress: Whether to compress the JSON file using gzip.
+		:param \*\*kwargs: Keyword arguments to pass to the JSON serialisation function.
 
 		.. versionadded:: 0.5.0
 
@@ -562,37 +566,60 @@ def dump_json(
 			Now uses :meth:`PathPlus.write_clean <domdf_python_tools.paths.PathPlus.write_clean>`
 			rather than :meth:`PathPlus.write_text <domdf_python_tools.paths.PathPlus.write_text>`,
 			and returns :py:obj:`None` rather than :class:`int`.
+
+		.. versionchanged:: 1.9.0
+
+			Added the ``compress`` keyword-only argument.
 		"""
 
-		return self.write_clean(
-				json_library.dumps(data, **kwargs),
-				encoding=encoding,
-				errors=errors,
-				)
+		if compress:
+			with gzip.open(self, mode="wt", encoding=encoding, errors=errors) as fp:
+				fp.write(json_library.dumps(data, **kwargs))
+
+		else:
+			self.write_clean(
+					json_library.dumps(data, **kwargs),
+					encoding=encoding,
+					errors=errors,
+					)
 
 	def load_json(
 			self,
 			encoding: Optional[str] = "UTF-8",
 			errors: Optional[str] = None,
 			json_library: JsonLibrary = json,  # type: ignore
+			*,
+			decompress: bool = False,
 			**kwargs,
 			) -> Any:
-		"""
+		r"""
 		Load JSON data from the file.
 
 		:param encoding: The encoding to write to the file in.
 		:param errors:
 		:param json_library: The JSON serialisation library to use.
 		:default json_library: :mod:`json`
-		:param kwargs: Keyword arguments to pass to the JSON deserialisation function.
+		:param decompress: Whether to decompress the JSON file using gzip.
+			Will raise an exception if the file is not compressed.
+		:param \*\*kwargs: Keyword arguments to pass to the JSON deserialisation function.
 
 		:return: The deserialised JSON data.
 
 		.. versionadded:: 0.5.0
+
+		.. versionchanged:: 1.9.0
+
+			Added the ``compress`` keyword-only argument.
 		"""
 
+		if decompress:
+			with gzip.open(self, mode="rt", encoding=encoding, errors=errors) as fp:
+				content = fp.read()
+		else:
+			content = self.read_text(encoding=encoding, errors=errors)
+
 		return json_library.loads(
-				self.read_text(encoding=encoding, errors=errors),
+				content,
 				**kwargs,
 				)
 

domdf_python_tools/terminal_colours.py

@@ -66,11 +66,12 @@
 
 # stdlib
 import re
+import warnings
 from abc import ABC
 from typing import List, Pattern
 
 # 3rd party
-from colorama import init  # type: ignore
+import colorama  # type: ignore
 from typing_extensions import Final
 
 __all__ = [
@@ -94,7 +95,14 @@
 		"strip_ansi",
 		]
 
-init()
+warnings.warn(
+		"domdf_python_tools.terminal_colours is deprecated and will be removed in v2. "
+		"Use consolekit.terminal_colours instead.",
+		DeprecationWarning,
+		stacklevel=2,
+		)
+
+colorama.init()
 
 CSI: Final[str] = "\u001b["
 OSC: Final[str] = "\u001b]"

domdf_python_tools/utils.py

@@ -22,7 +22,6 @@
 	:func:`~domdf_python_tools.iterative.Len`, and
 	:func:`~domdf_python_tools.iterative.double_chain`
 	moved to :func:`domdf_python_tools.iterative`.
-
 	They can still be imported from here until version 2.0.0, but that use is deprecated.
 """
 #
@@ -93,13 +92,15 @@
 # this package
 import domdf_python_tools.words
 from domdf_python_tools import __version__, iterative
-from domdf_python_tools.terminal_colours import Colour, Fore
 from domdf_python_tools.typing import HasHead, String
 
 if typing.TYPE_CHECKING or domdf_python_tools.__docs:  # pragma: no cover
 	# 3rd party
 	from pandas import DataFrame, Series  # type: ignore
 
+	# this package
+	from domdf_python_tools.terminal_colours import Colour, Fore
+
 	Series.__module__ = "pandas"
 	DataFrame.__module__ = "pandas"
 
@@ -256,6 +257,8 @@ def posargs2kwargs(
 	"""
 	Convert the positional args in ``args`` to kwargs, based on the relative order of ``args`` and ``posarg_names``.
 
+	.. important:: Python 3.8's Positional-Only Parameters (:pep:`570`) are not supported.
+
 	:param args: List of positional arguments provided to a function.
 	:param posarg_names: Either a list of positional argument names for the function, or the function object.
 	:param kwargs: Optional mapping of keyword argument names to values.
@@ -275,6 +278,8 @@ def posargs2kwargs(
 
 	kwargs.update(zip(posarg_names, args))
 
+	# TODO: positional only arguments
+
 	return kwargs
 
 
@@ -623,8 +628,8 @@ def coloured_diff(
 		tofiledate: str = '',
 		n: int = 3,
 		lineterm: str = '\n',
-		removed_colour: Colour = Fore.RED,
-		added_colour: Colour = Fore.GREEN,
+		removed_colour: Optional["Colour"] = None,
+		added_colour: Optional["Colour"] = None,
 		) -> str:
 	r"""
 	Compare two sequences of lines; generate the delta as a unified diff.
@@ -679,6 +684,15 @@ def coloured_diff(
 	# this package
 	from domdf_python_tools.stringlist import StringList
 
+	with warnings.catch_warnings():
+		warnings.simplefilter("ignore", DeprecationWarning)
+
+		# this package
+		from domdf_python_tools.terminal_colours import Fore
+
+	removed_colour = removed_colour or Fore.RED
+	added_colour = added_colour or Fore.GREEN
+
 	buf = StringList()
 	diff = difflib.unified_diff(a, b, fromfile, tofile, fromfiledate, tofiledate, n, lineterm)
 

tests/test_paths.py

@@ -580,6 +580,18 @@ def test_dump_json(tmpdir):
 """)
 
 
+def test_dump_json_gzip(tmpdir):
+	tmpdir_p = PathPlus(tmpdir)
+
+	tmp_file = tmpdir_p / "test.txt"
+
+	tmp_file.dump_json({"key": "value", "int": 1234, "float": 12.34}, compress=True)
+	assert tmp_file.load_json(decompress=True) == {"key": "value", "int": 1234, "float": 12.34}
+
+	tmp_file.dump_json({"key": "value", "int": 1234, "float": 12.34}, indent=2, compress=True)
+	assert tmp_file.load_json(decompress=True) == {"key": "value", "int": 1234, "float": 12.34}
+
+
 def test_load_json(tmpdir):
 	tmpdir_p = PathPlus(tmpdir)