dstamp 2__tar.gz → 4__tar.gz

dstamp-4/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: dstamp
+Version: 4
+Summary: CLI app for generating timestamps for use in Discord chats.
+Keywords: discord,generator,timestamp
+Author: Mariusz Tang
+Author-email: Mariusz Tang <dev@mariusztang.com>
+License-Expression: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Topic :: Communications :: Chat
+Requires-Dist: argcomplete>=3.6.3
+Requires-Dist: logassert>=8.6
+Requires-Dist: platformdirs>=4.10.0
+Requires-Dist: pyperclip>=1.11.0
+Requires-Python: >=3.14
+Project-URL: Issues, https://github.com/mariusz-tang/dstamp/issues
+Project-URL: Repository, https://github.com/mariusz-tang/dstamp
+Description-Content-Type: text/markdown
+
+# dstamp
+
+CLI app for generating timestamps for use in Discord chats.
+
+*Note*: This is a complete rewrite of the original project from the ground up,
+using the standard argparse module instead of cyclopts.
+
+## Installation
+
+Install using [pipx] or [uv]:
+
+```bash
+pipx install dstamp
+```
+
+```bash
+uv tool install dstamp
+```
+
+[pipx]: https://pipx.pypa.io/stable/
+[uv]: https://docs.astral.sh/uv/
+
+## Usage
+
+```bash
+# Get the current time.
+dstamp get
+
+# Get the current time, to the nearest 15 minutes.
+dstamp get --precision 15m
+
+# Get the time 20 minutes from now.
+dstamp in 20m
+
+# Show the default config file location.
+dstamp show-config
+```
+
+See the help messages for full usage information:
+
+```bash
+dstamp --help
+dstamp -h get
+dstamp -h in
+```
+
+### Configuration
+
+Dstamp supports configuration by TOML file. See `dstamp -h show-config` for full
+information. The config file location can be overridden using the `--config`
+option.
+
+## Logs
+
+Dstamp writes logs to a file. Use `dstamp show-log` to get the file location.
+
+## Shell completion
+
+Dstamp supports shell completion using [argcomplete]. See the argcomplete
+documentation for setup instructions.
+
+[argcomplete]: https://github.com/kislyuk/argcomplete#activating-global-completion
+
+## Versioning
+
+This project uses an `MAJOR.MINOR` versioning scheme. `MAJOR` is incremented for
+significant feature additions or changes. Everything else increments `MINOR`
+only. `MINOR` is omitted if it is zero.
+
+## Contributing
+
+If you'd like to see something added to dstamp or if you would like to add something
+yourself, please see [CONTRIBUTING](./CONTRIBUTING.md)!
+
+Please also see the above if you have a bug to report.

dstamp-4/README.md

@@ -0,0 +1,75 @@
+# dstamp
+
+CLI app for generating timestamps for use in Discord chats.
+
+*Note*: This is a complete rewrite of the original project from the ground up,
+using the standard argparse module instead of cyclopts.
+
+## Installation
+
+Install using [pipx] or [uv]:
+
+```bash
+pipx install dstamp
+```
+
+```bash
+uv tool install dstamp
+```
+
+[pipx]: https://pipx.pypa.io/stable/
+[uv]: https://docs.astral.sh/uv/
+
+## Usage
+
+```bash
+# Get the current time.
+dstamp get
+
+# Get the current time, to the nearest 15 minutes.
+dstamp get --precision 15m
+
+# Get the time 20 minutes from now.
+dstamp in 20m
+
+# Show the default config file location.
+dstamp show-config
+```
+
+See the help messages for full usage information:
+
+```bash
+dstamp --help
+dstamp -h get
+dstamp -h in
+```
+
+### Configuration
+
+Dstamp supports configuration by TOML file. See `dstamp -h show-config` for full
+information. The config file location can be overridden using the `--config`
+option.
+
+## Logs
+
+Dstamp writes logs to a file. Use `dstamp show-log` to get the file location.
+
+## Shell completion
+
+Dstamp supports shell completion using [argcomplete]. See the argcomplete
+documentation for setup instructions.
+
+[argcomplete]: https://github.com/kislyuk/argcomplete#activating-global-completion
+
+## Versioning
+
+This project uses an `MAJOR.MINOR` versioning scheme. `MAJOR` is incremented for
+significant feature additions or changes. Everything else increments `MINOR`
+only. `MINOR` is omitted if it is zero.
+
+## Contributing
+
+If you'd like to see something added to dstamp or if you would like to add something
+yourself, please see [CONTRIBUTING](./CONTRIBUTING.md)!
+
+Please also see the above if you have a bug to report.

{dstamp-2 → dstamp-4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dstamp"
-version = "2"
+version = "4"
 description = "CLI app for generating timestamps for use in Discord chats."
 readme = "README.md"
 requires-python = ">=3.14"
@@ -8,16 +8,16 @@ license = "MIT"
 authors = [{ name = "Mariusz Tang", email = "dev@mariusztang.com" }]
 keywords = ["discord", "generator", "timestamp"]
 classifiers = [
-  "Development Status :: 4 - Beta",
+  "Development Status :: 5 - Production/Stable",
   "Environment :: Console",
   "Intended Audience :: End Users/Desktop",
   "Topic :: Communications :: Chat",
 ]
 dependencies = [
-  "cyclopts>=4.11.0",
-  "platformdirs>=4.9.6",
+  "argcomplete>=3.6.3",
+  "logassert>=8.6",
+  "platformdirs>=4.10.0",
   "pyperclip>=1.11.0",
-  "pytest-mock>=3.15.1",
 ]
 
 [project.urls]
@@ -25,13 +25,14 @@ Issues = "https://github.com/mariusz-tang/dstamp/issues"
 Repository = "https://github.com/mariusz-tang/dstamp"
 
 [project.scripts]
-dstamp = "dstamp.main:app.meta"
+dstamp = "dstamp.cli:run"
 
 [dependency-groups]
 dev = [
   "coverage>=7.13.5",
   "freezegun>=1.5.5",
   "pytest>=9.0.3",
+  "pytest-mock>=3.15.1",
   "ty>=0.0.34",
 ]
 
@@ -43,7 +44,6 @@ build-backend = "uv_build"
 branch = true
 command_line = "-m pytest"
 source = ["src/"]
-omit = ["src/dstamp/__main__.py", "src/dstamp/console.py"]
 
 [tool.coverage.report]
 skip_empty = true
@@ -64,6 +64,7 @@ select = [
   "B",  # flake8-bugbear
   "C4",  # flake8-comprehensions
   "C90",  # mccabe
+  "D",  # pydocstyle
   "E",  # pycodestyle error
   "F",  # pyflakes
   "FURB",  # refurb
@@ -79,5 +80,6 @@ select = [
   "UP",  # pyupgrade
   "W",  # pycodestyle warning
 ]
-ignore = ["TRY003"]  # This rule is too strict, especially for ValueError.
-flake8-pytest-style.parametrize-names-type = "csv"
+pydocstyle.convention = "pep257"
+per-file-ignores = { "tests/**/*" = ["D"] }
+flake8-annotations.allow-star-arg-any = true

dstamp-4/src/dstamp/__init__.py

@@ -0,0 +1,3 @@
+"""CLI tool for printing Discord timestamps."""
+
+APP_NAME = "dstamp"

dstamp-4/src/dstamp/cli.py

@@ -0,0 +1,172 @@
+# PYTHON_ARGCOMPLETE_OK
+"""Dstamp's CLI interface."""
+
+import argparse
+import logging
+import logging.config
+import pathlib
+import sys
+import tomllib
+from collections.abc import Iterable
+
+import argcomplete
+import pyperclip
+
+import dstamp.logging
+from dstamp import config, exceptions, subcommands
+
+logger = logging.getLogger(__name__)
+
+# Use a base parser to change the help flag's help message.
+base_parser = argparse.ArgumentParser(add_help=False)
+base_parser.add_argument(
+    "-h",
+    "--help",
+    action="help",
+    help="Show this help message and exit.",
+)
+
+
+def construct_parser(config: dict | None = None) -> argparse.ArgumentParser:
+    """Create the dstamp CLI argument parser."""
+    # Add the help option manually so we can change the help message.
+    parser = argparse.ArgumentParser(
+        add_help=False,
+        parents=[base_parser],
+        description="Discord timestamp generator.",
+        epilog="Some options can be set via config file. See %(prog)s -h show-config",
+        suggest_on_error=True,
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version="%(prog)s 4",
+        help="Show version number and exit.",
+    )
+    parser.add_argument(
+        "--config",
+        metavar="CONFIG_PATH",
+        type=pathlib.Path,
+        help="Alternative config file to use instead of the default. Should be "
+        "a TOML file.",
+    )
+    parser.add_argument(
+        "--quiet",
+        action=argparse.BooleanOptionalAction,
+        help="Do not print warnings to the console. Disabled by default.",
+    )
+    parser.add_argument(
+        "--verbose",
+        action=argparse.BooleanOptionalAction,
+        help="Print detailed info messages to the console. Takes precedence over "
+        "--quiet. Disabled by default.",
+    )
+
+    subparsers = parser.add_subparsers(title="commands")
+    subcommands.register_all(subparsers, config or {})
+
+    return parser
+
+
+def run(args: Iterable[str] | None = None) -> None:
+    """Parse `args` as CLI arguments and execute the resulting command."""
+    parser = construct_parser()
+    argcomplete.autocomplete(parser)
+
+    # Move help flags past subcommands so the most specific help message is shown.
+    args = _move_help_to_end(args or sys.argv[1:])
+    parsed_args = parser.parse_args(args)
+
+    # Print help if no arguments are provided.
+    if not hasattr(parsed_args, "func"):
+        parser.print_help()
+        return
+
+    # Read the config file.
+    config_path, config_, unknown_keys, config_warning = _get_config(parsed_args.config)
+
+    # Re-parse the arguments with defaults from the config.
+    # We use this method because the config path needs to be known at parse
+    # time, but we cannot determine an overridden config path before parsing.
+    parser = construct_parser(config_)
+    parsed_args = parser.parse_args(args)
+
+    # Configure logging only after reading the config.
+    verbosity = (
+        "verbose" if parsed_args.verbose else "quiet" if parsed_args.quiet else "normal"
+    )
+    logging.config.dictConfig(dstamp.logging.get_config(verbosity))
+
+    # Now we can start logging.
+    logger.info(f"args: {args or sys.argv[1:]}")
+
+    logger.info(f"using config in {config_path}")
+    if config_warning:
+        logger.warning(config_warning)
+
+    logger.info(f"computed config options: {config_}")
+    if unknown_keys:
+        logger.warning(f"unknown keys in config file: {', '.join(unknown_keys)}")
+
+    try:
+        parsed_args.func(parsed_args)
+    except exceptions.DstampError as e:
+        parser.error(str(e))
+    except pyperclip.PyperclipException as e:
+        parser.error(f"there was a problem with the clipboard manager: {e}")
+    except Exception:
+        logger.exception("An unexpected error occurred.")
+        parser.error("an unexpected error occurred; please report this to dstamp")
+
+
+def _move_help_to_end(args: Iterable[str]) -> Iterable[str]:
+    args = list(args)
+    if "-h" not in args and "--help" not in args:
+        return args
+
+    # Remove --version so it doesn't override the help flag if present.
+    _remove_arg(args, "--version")
+    _remove_arg(args, "--help")
+    _remove_arg(args, "-h")
+
+    args.append("--help")
+    return args
+
+
+def _remove_arg(args: list[str], arg: str) -> None:
+    while arg in args:
+        args.remove(arg)
+
+
+def _get_config(
+    config_path_arg: pathlib.Path | None,
+) -> tuple[pathlib.Path, dict, set, str | None]:
+    """Get config from `config_path_arg`.
+
+    Returns the effective config path, cleaned config, unknown keys set, and
+    a warning message if applicable.
+    """
+    log_warning = None
+
+    # Log if config path is specified at the command line but cannot be used.
+    if config_path_arg:
+        if not config_path_arg.exists():
+            log_warning = "specified config file does not exist"
+        elif not config_path_arg.is_file():
+            log_warning = "specified config path is not a file"
+
+    # Default result if we cannot read a file.
+    config_cleaned = {}
+    unknown_keys = set()
+
+    config_path = config_path_arg or config.default_path()
+    if config_path.is_file():
+        try:
+            config_raw = tomllib.loads(config_path.read_text())
+        except tomllib.TOMLDecodeError:
+            log_warning = "config file is not valid TOML"
+        else:
+            # Override result with file contents.
+            config_cleaned, unknown_keys = config.clean(config_raw)
+
+    return config_path, config_cleaned, unknown_keys, log_warning

dstamp-4/src/dstamp/config.py

@@ -0,0 +1,40 @@
+"""Config file utilities.
+
+The functions in this module do not create a config file if one does not exist.
+"""
+
+import pathlib
+from typing import Any
+
+import platformdirs
+
+import dstamp
+
+
+def default_path() -> pathlib.Path:
+    """Return the default config file path.
+
+    Note that the file does not necessarily exist.
+    """
+    config_dir = platformdirs.user_config_path(dstamp.APP_NAME)
+    return config_dir / "config.toml"
+
+
+_VALID_KEYS = {
+    "copy",
+    "format",
+    "precision",
+    "quiet",
+    "verbose",
+}
+
+
+def clean(config: dict) -> tuple[dict[str, Any], set[str]]:
+    """Clean a config dict so it contains only valid keys.
+
+    Returns a dictionary containing the cleaned config and a set containing the
+    invalid keys that were found in the input.
+    """
+    cleaned_config = {key: value for key, value in config.items() if key in _VALID_KEYS}
+    unknown_keys = config.keys() - _VALID_KEYS
+    return cleaned_config, unknown_keys

dstamp-4/src/dstamp/discord.py

@@ -0,0 +1,14 @@
+"""Discord-related formatting utilities."""
+
+from datetime import datetime
+
+
+def timestamp(time: datetime, format_code: str) -> str:
+    """Return a Discord timestamp representing `time`.
+
+    :param time: The time to respresent. If it has a fractional timestamp, it
+    is truncated towards zero.
+    :param format_code: The format code to use. Tells Discord how to format the
+    timestamp.
+    """
+    return f"<t:{int(time.timestamp())}:{format_code}>"

dstamp-4/src/dstamp/exceptions.py

@@ -0,0 +1,62 @@
+"""Exception classes for errors raised by dstamp."""
+
+from dstamp import round
+
+
+class DstampError(Exception):
+    """Base class for all exceptions raised by dstamp."""
+
+
+class ParserInputError(DstampError):
+    """Base class for parser input errors."""
+
+    def __init__(self, input: str, output_type: type) -> None:
+        """Initialize an error instance with a formatted error message.
+
+        :param input: The input string which caused the parser to fail.
+        :param output_type: The expected output type.
+        """
+        self.input = input
+        self.output_type = output_type
+        super().__init__(self._format_message())
+
+    def _format_message(self) -> str:
+        raise NotImplementedError  # pragma: no cover
+
+
+class ParserFormatError(ParserInputError):
+    """Raised when the input to a parser was not in the right format."""
+
+    def _format_message(self) -> str:
+        return f"invalid {self.output_type.__name__.lower()} format: {repr(self.input)}"
+
+
+class ParserValueError(ParserInputError):
+    """Raised when an invalid time object would be created."""
+
+    def _format_message(self) -> str:
+        return (
+            f"input represents an invalid {self.output_type.__name__.lower()}: "
+            f"{repr(self.input)}"
+        )
+
+
+class PrecisionQuantityError(DstampError):
+    """Raised when the `Precision` constructor receives an invalid quantity."""
+
+    def __init__(self, quantity: int, unit: round.Unit) -> None:
+        """Initialize an error instance with a formatted error message.
+
+        :param quantity: The quantity passed to the `Precision` constructor.
+        :param unit: The unit object passed to the `Precision` constructor.
+        """
+        self.quantity = quantity
+        self.unit = unit
+        super().__init__(self._format_message())
+
+    def _format_message(self) -> str:
+        return (
+            f"quantity for {self.unit.name.lower()} must be between 1 and "
+            f"{self.unit.max_quantity} (inclusive), and must be a factor of "
+            f"{self.unit.max_quantity} (actual quantity was {self.quantity})."
+        )

dstamp-4/src/dstamp/logging.py

@@ -0,0 +1,52 @@
+"""Defines dstamp's logging configuration."""
+
+import platformdirs
+
+import dstamp
+
+LOG_DIR = platformdirs.user_log_path(dstamp.APP_NAME, ensure_exists=True)
+
+CONFIG = {
+    "version": 1,
+    "formatters": {
+        "short": {"format": "%(levelname)s: %(message)s"},
+        "full": {"format": "%(asctime)s %(levelname)s: %(name)s: %(message)s"},
+    },
+    "handlers": {
+        "console": {
+            "class": "logging.StreamHandler",
+            "formatter": "short",
+            "level": "WARNING",
+        },
+        "file": {
+            "class": "logging.handlers.RotatingFileHandler",
+            "formatter": "full",
+            "filename": LOG_DIR / f"{dstamp.APP_NAME}.log",
+            "encoding": "utf-8",
+            "maxBytes": 50_000,
+            "backupCount": 1,
+        },
+    },
+    "root": {
+        "level": "INFO",
+        "handlers": ["console", "file"],
+    },
+    "disable_existing_loggers": False,
+}
+
+
+def get_config(verbosity: str) -> dict:
+    """Get an appropriate logging configuration for the given `verbosity`.
+
+    :param verbosity: recognized values are "quiet" and "verbose". Other values
+    are ignored and produce the default config.
+    """
+    # Use unspecific type annotation to avoid type errors below.
+    base: dict = CONFIG
+
+    if verbosity == "quiet":
+        base["root"]["handlers"].remove("console")
+    elif verbosity == "verbose":
+        base["handlers"]["console"]["level"] = "INFO"
+
+    return base