knickknacks 0.5.0__tar.gz

knickknacks-0.5.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Nick Stockton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

knickknacks-0.5.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.1
+Name: knickknacks
+Version: 0.5.0
+Summary: Small, reusable, miscellaneous pieces of code.
+Keywords: utilities,misc,snippets,reusable
+Author-Email: Nick Stockton <nstockton@users.noreply.github.com>
+License: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: POSIX :: BSD
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Unix
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Project-URL: homepage, https://github.com/nstockton/knickknacks
+Project-URL: repository, https://github.com/nstockton/knickknacks
+Project-URL: documentation, https://nstockton.github.io/knickknacks
+Requires-Python: <4.0,>=3.9
+Requires-Dist: backports-strenum<2.0,>=1.3; python_version < "3.11"
+Requires-Dist: typing-extensions<5.0,>=4.8; python_version < "3.12"
+Description-Content-Type: text/markdown
+
+# Knickknacks
+
+Small, reusable, miscellaneous pieces of code.
+
+## License And Credits
+
+Knickknacks is licensed under the terms of the [MIT License.](https://raw.githubusercontent.com/nstockton/knickknacks/master/LICENSE.txt "Knickknacks License")
+
+### Running From Source
+
+Install the [Python interpreter,](https://python.org "Python Home Page") and make sure it's in your path before running this package.
+
+After Python is installed, execute the following commands from the top level directory of this repository to install the module dependencies.
+```
+python -m venv .venv
+source .venv/bin/activate
+pip install --upgrade --require-hashes --requirement requirements-uv.txt
+uv sync
+pre-commit install -t pre-commit
+pre-commit install -t pre-push
+```

knickknacks-0.5.0/README.md

@@ -0,0 +1,21 @@
+# Knickknacks
+
+Small, reusable, miscellaneous pieces of code.
+
+## License And Credits
+
+Knickknacks is licensed under the terms of the [MIT License.](https://raw.githubusercontent.com/nstockton/knickknacks/master/LICENSE.txt "Knickknacks License")
+
+### Running From Source
+
+Install the [Python interpreter,](https://python.org "Python Home Page") and make sure it's in your path before running this package.
+
+After Python is installed, execute the following commands from the top level directory of this repository to install the module dependencies.
+```
+python -m venv .venv
+source .venv/bin/activate
+pip install --upgrade --require-hashes --requirement requirements-uv.txt
+uv sync
+pre-commit install -t pre-commit
+pre-commit install -t pre-push
+```

knickknacks-0.5.0/pyproject.toml

@@ -0,0 +1,291 @@
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[project]
+name = "knickknacks"
+authors = [
+    { name = "Nick Stockton", email = "nstockton@users.noreply.github.com" },
+]
+description = "Small, reusable, miscellaneous pieces of code."
+readme = "README.md"
+requires-python = ">=3.9,<4.0"
+dependencies = [
+    "backports-strenum>=1.3,<2.0; python_version < \"3.11\"",
+    "typing-extensions>=4.8,<5.0; python_version < \"3.12\"",
+]
+dynamic = []
+keywords = [
+    "utilities",
+    "misc",
+    "snippets",
+    "reusable",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: Implementation",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Operating System :: MacOS",
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: Microsoft",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: OS Independent",
+    "Operating System :: POSIX",
+    "Operating System :: POSIX :: BSD",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Unix",
+    "Topic :: Software Development",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+version = "0.5.0"
+
+[project.license]
+text = "MIT"
+
+[project.urls]
+homepage = "https://github.com/nstockton/knickknacks"
+repository = "https://github.com/nstockton/knickknacks"
+documentation = "https://nstockton.github.io/knickknacks"
+
+[dependency-groups]
+dev = [
+    "pre-commit>=3.5,<4.0",
+]
+docs = [
+    "jinja2==3.0.3",
+    "mkdocs==1.2.3",
+    "mkdocs-autorefs==0.3.1",
+    "mkdocs-material==8.1.3",
+    "mkdocs-material-extensions==1.0.3",
+    "mkdocstrings==0.17.0",
+    "pytkdocs @ git+https://github.com/nstockton/pytkdocs.git@9991d493b408c403ac5691074e2af2e509f22926",
+]
+lint = [
+    "isort>=5.13,<6.0",
+    "mypy>=1.14,<2.0",
+    "ruff>=0.9,<1.0",
+]
+test = [
+    "coverage[toml]>=7.6,<8.0",
+]
+
+[tool.pdm.build]
+package-dir = "src"
+includes = [
+    "src/knickknacks",
+]
+excludes = []
+source-includes = [
+    "tests",
+    "uv.lock",
+]
+
+[tool.pdm.version]
+fallback_version = "0.0.0"
+source = "scm"
+tag_filter = "[vV][0-9]*"
+tag_regex = "^(?:[vV])(?P<version>\\d+\\.\\d+\\.\\d+)(?:.*)$"
+write_to = "knickknacks/_version.py"
+write_template = "__version__: str = \"{}\"\r\n"
+
+[tool.uv]
+default-groups = [
+    "dev",
+    "docs",
+    "lint",
+    "test",
+]
+upgrade-package = [
+    "knickknacks",
+]
+
+[tool.ruff]
+extend-include = [
+    "*.pyw",
+]
+force-exclude = true
+line-length = 110
+
+[tool.ruff.format]
+docstring-code-format = false
+indent-style = "tab"
+line-ending = "cr-lf"
+
+[tool.ruff.lint]
+preview = true
+select = [
+    "ALL",
+]
+extend-select = [
+    "D213",
+]
+ignore = [
+    "ANN",
+    "ARG",
+    "B019",
+    "COM812",
+    "D105",
+    "D206",
+    "D212",
+    "EM",
+    "G",
+    "I",
+    "PT",
+    "T20",
+    "TCH",
+    "TRY003",
+    "UP007",
+    "UP045",
+    "W191",
+]
+typing-modules = [
+    "knickknacks.typedef",
+]
+unfixable = []
+
+[tool.ruff.lint.flake8-builtins]
+builtins-ignorelist = []
+
+[tool.ruff.lint.flake8-copyright]
+author = "Nick Stockton"
+min-file-size = 1
+
+[tool.ruff.lint.flake8-implicit-str-concat]
+allow-multiline = false
+
+[tool.ruff.lint.mccabe]
+max-complexity = 15
+
+[tool.ruff.lint.per-file-ignores]
+"**/__init__.py" = [
+    "D1",
+]
+"**/_version.py" = [
+    "CPY001",
+]
+"./tests/**" = [
+    "D1",
+    "PLR6301",
+]
+"**/typedef.py" = [
+    "F401",
+]
+"./src/knickknacks/backports.py" = [
+    "PLR2004",
+]
+"./src/knickknacks/numbers.py" = [
+    "A005",
+]
+"./src/knickknacks/testing.py" = [
+    "N802",
+    "N815",
+]
+"./src/knickknacks/xml.py" = [
+    "A005",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+ignore-decorators = [
+    "typing.overload",
+]
+
+[tool.ruff.lint.ruff]
+parenthesize-tuple-in-subscript = true
+
+[tool.coverage.report]
+precision = 0
+fail_under = 100.0
+show_missing = true
+skip_covered = true
+sort = "Cover"
+exclude_lines = [
+    "\\#\\s*pragma: no cover",
+    "^\\s*raise AssertionError\\b",
+    "^\\s*raise NotImplementedError\\b",
+    "^\\s*def __repr__",
+    "^\\s*def __str__",
+    "^\\s*if __name__ == .__main__.:",
+]
+
+[tool.coverage.run]
+source = [
+    "knickknacks",
+]
+omit = [
+    "src/knickknacks/backports.py",
+    "src/knickknacks/typedef.py",
+]
+
+[tool.isort]
+line_length = 110
+color_output = false
+supported_extensions = [
+    "py",
+    "pyi",
+    "pys",
+    "pyw",
+]
+extend_skip = []
+indent = "tab"
+atomic = true
+dedup_headings = true
+multi_line_output = 3
+include_trailing_comma = true
+force_grid_wrap = 0
+use_parentheses = true
+ensure_newline_before_comments = true
+indented_import_headings = false
+float_to_top = true
+lines_after_imports = 2
+force_adds = false
+from_first = false
+combine_as_imports = false
+order_by_type = true
+reverse_relative = true
+add_imports = [
+    "from __future__ import annotations",
+]
+default_section = "STDLIB"
+import_heading_future = "Future Modules:"
+import_heading_stdlib = "Built-in Modules:"
+import_heading_thirdparty = "Third-party Modules:"
+known_third_party = [
+    "backports.strenum",
+    "typing_extensions",
+]
+import_heading_firstparty = "Knickknacks Modules:"
+known_first_party = [
+    "knickknacks",
+]
+import_heading_localfolder = "Local Modules:"
+
+[tool.mypy]
+files = [
+    "src/knickknacks",
+    "tests",
+]
+exclude = "^$"
+local_partial_types = true
+strict = true
+disallow_any_unimported = true
+disallow_any_decorated = true
+warn_unreachable = true
+show_error_codes = true
+no_color_output = true
+overrides = [
+    { module = "tests.*", disallow_any_decorated = false },
+]

knickknacks-0.5.0/src/knickknacks/__init__.py

@@ -0,0 +1,37 @@
+# Copyright (c) 2025 Nick Stockton
+# -----------------------------------------------------------------------------
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# -----------------------------------------------------------------------------
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+# -----------------------------------------------------------------------------
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+# Future Modules:
+from __future__ import annotations
+
+# Built-in Modules:
+from contextlib import suppress
+from typing import TYPE_CHECKING
+
+
+__version__: str = "0.0.0"
+if not TYPE_CHECKING:
+	with suppress(ImportError):
+		from ._version import __version__
+
+
+__all__: list[str] = [
+	"__version__",
+]

knickknacks-0.5.0/src/knickknacks/_version.py

@@ -0,0 +1 @@
+__version__: str = "0.5.0"

knickknacks-0.5.0/src/knickknacks/backports.py

@@ -0,0 +1,91 @@
+# Copyright (c) 2025 Nick Stockton
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+"""Backported classes and functions."""
+
+# Future Modules:
+from __future__ import annotations
+
+# Built-in Modules:
+import io
+import pathlib
+import sys
+from typing import Optional
+
+
+if sys.version_info >= (3, 11):
+	from enum import StrEnum
+else:
+	from backports.strenum import StrEnum
+
+
+class Path(pathlib.Path):
+	"""
+	Backported pathlib.Path functionality.
+
+	Currently backports the newline argument From 3.13 read_text, and 3.10 write_text.
+	"""
+
+	def read_text(
+		self, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None
+	) -> str:
+		"""
+		Open the file in text mode, read it, and close the file.
+
+		Args:
+			encoding: The character encoding to use.
+			errors: How encoding errors should be handled.
+			newline: How newlines should be handled.
+
+		Returns:
+			The contents of the file.
+		"""
+		if sys.version_info >= (3, 13):
+			text = super().read_text(encoding, errors, newline)
+		else:
+			if hasattr(io, "text_encoding"):
+				encoding = io.text_encoding(encoding)
+			with self.open(mode="r", encoding=encoding, errors=errors, newline=newline) as f:
+				text = f.read()
+		return text
+
+	def write_text(
+		self,
+		data: str,
+		encoding: Optional[str] = None,
+		errors: Optional[str] = None,
+		newline: Optional[str] = None,
+	) -> int:
+		"""
+		Open the file in text mode, write to it, and close the file.
+
+		Args:
+			data: The data to be written.
+			encoding: The character encoding to use.
+			errors: How encoding errors should be handled.
+			newline: How newlines should be handled.
+
+		Returns:
+			The number of bytes written.
+
+		Raises:
+			TypeError: Data is not an instance of `str`.
+		"""
+		if sys.version_info >= (3, 10):
+			num_written = super().write_text(data, encoding, errors, newline)
+		else:
+			if not isinstance(data, str):
+				raise TypeError(f"data must be str, not {data.__class__.__name__}")
+			if hasattr(io, "text_encoding"):
+				encoding = io.text_encoding(encoding)
+			with self.open(mode="w", encoding=encoding, errors=errors, newline=newline) as f:
+				num_written = f.write(data)
+		return num_written
+
+
+__all__: list[str] = [
+	"Path",
+	"StrEnum",
+]