dstamp 2__tar.gz → 3__tar.gz

dstamp-3/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: dstamp
+Version: 3
+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 :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Topic :: Communications :: Chat
+Requires-Dist: argcomplete>=3.6.3
+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
+
+# Show the config file location.
+dstamp show-config
+```
+
+See the help messages for full usage information:
+
+```bash
+dstamp -h
+dstamp -h get
+```
+
+### Configuration
+
+Dstamp supports configuration by TOML file. See `dstamp -h show-config` for full
+information.
+
+## 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-3/README.md

@@ -0,0 +1,66 @@
+# 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
+
+# Show the config file location.
+dstamp show-config
+```
+
+See the help messages for full usage information:
+
+```bash
+dstamp -h
+dstamp -h get
+```
+
+### Configuration
+
+Dstamp supports configuration by TOML file. See `dstamp -h show-config` for full
+information.
+
+## 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-3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dstamp"
-version = "2"
+version = "3"
 description = "CLI app for generating timestamps for use in Discord chats."
 readme = "README.md"
 requires-python = ">=3.14"
@@ -14,10 +14,9 @@ classifiers = [
   "Topic :: Communications :: Chat",
 ]
 dependencies = [
-  "cyclopts>=4.11.0",
-  "platformdirs>=4.9.6",
+  "argcomplete>=3.6.3",
+  "platformdirs>=4.10.0",
   "pyperclip>=1.11.0",
-  "pytest-mock>=3.15.1",
 ]
 
 [project.urls]
@@ -25,13 +24,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 +43,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 +63,7 @@ select = [
   "B",  # flake8-bugbear
   "C4",  # flake8-comprehensions
   "C90",  # mccabe
+  "D",  # pydocstyle
   "E",  # pycodestyle error
   "F",  # pyflakes
   "FURB",  # refurb
@@ -79,5 +79,5 @@ 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"] }

dstamp-3/src/dstamp/__init__.py

@@ -0,0 +1 @@
+"""CLI tool for printing Discord timestamps."""

dstamp-3/src/dstamp/cli.py

@@ -0,0 +1,53 @@
+# PYTHON_ARGCOMPLETE_OK
+"""Dstamp's CLI interface."""
+
+import argparse
+from collections.abc import Iterable
+
+import argcomplete
+
+from dstamp import exceptions, subcommands
+
+
+def construct_parser() -> 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,
+        description="Discord timestamp generator",
+    )
+    parser.add_argument(
+        "-h",
+        "--help",
+        action="store_true",
+        help="Show this help message and exit. For command-specific help, use "
+        "%(prog)s -h COMMAND",
+    )
+    parser.set_defaults(print_help=parser.print_help)
+    parser.add_argument(
+        "--version",
+        action="version",
+        version="%(prog)s 3",
+        help="Show version number and exit",
+    )
+
+    subparsers = parser.add_subparsers(title="commands")
+    subcommands.register_all(subparsers)
+
+    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)
+    parsed_args = parser.parse_args(args)
+
+    if not hasattr(parsed_args, "func") or parsed_args.help:
+        parsed_args.print_help()
+        return
+
+    try:
+        parsed_args.func(parsed_args)
+    except exceptions.DstampError as e:
+        parser.error(str(e))

dstamp-3/src/dstamp/config.py

@@ -0,0 +1,46 @@
+"""Config file utilities.
+
+The functions in this module do not create a config file if one does not exist.
+"""
+
+import pathlib
+import tomllib
+import warnings
+
+import platformdirs
+
+_APP_NAME = "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(_APP_NAME)
+    return config_dir / "config.toml"
+
+
+_VALID_KEYS = {
+    "copy",
+    "format",
+    "precision",
+}
+
+
+def parse(path: pathlib.Path) -> dict:
+    """Parse `path` as a config file and return the corresponding defaults dict.
+
+    If `path` does not exist, it is treated as if it were an empty file.
+    """
+    if not path.exists():
+        return {}
+
+    config = tomllib.loads(path.read_text())
+
+    if unknown_keys := config.keys() - _VALID_KEYS:
+        warnings.warn(
+            f"unknown keys in config file: {', '.join(unknown_keys)}", stacklevel=2
+        )
+
+    return config

dstamp-3/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-3/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-3/src/dstamp/parse.py

@@ -0,0 +1,129 @@
+"""Input-parsing utilities."""
+
+import datetime as dt
+import re
+from collections import Counter
+
+from dstamp import exceptions, round
+
+MONTHS = [
+    "jan",
+    "feb",
+    "mar",
+    "apr",
+    "may",
+    "jun",
+    "jul",
+    "aug",
+    "sep",
+    "oct",
+    "nov",
+    "dec",
+]
+
+
+def date(input: str) -> dt.date:
+    """Parse `input` as a date."""
+    if input == "today":
+        return dt.date.today()
+    if input in ["tomorrow", "tmrw"]:
+        return dt.date.today() + dt.timedelta(1)
+    if input == "yesterday":
+        return dt.date.today() - dt.timedelta(1)
+
+    m = re.fullmatch(rf"(\d+)({'|'.join(MONTHS)})(\d+)?", input.lower())
+    if not m:
+        raise exceptions.ParserFormatError(input, dt.date)
+
+    day = int(m[1])
+    month = MONTHS.index(m[2]) + 1
+    year = int(m[3]) if m[3] else dt.date.today().year
+
+    try:
+        return dt.date(year, month, day)
+    except ValueError as e:
+        raise exceptions.ParserValueError(input, dt.date) from e
+
+
+def time(input: str) -> dt.time:
+    """Parse `input` as a time."""
+    if input == "now":
+        return dt.datetime.now().time()
+    if input == "midnight":
+        return dt.time()
+    if input == "noon":
+        return dt.time(12)
+
+    m = re.fullmatch(r"(\d{1,2})(\d{2})?(\d{2})?(am|pm)?", input.lower())
+    if not m:
+        raise exceptions.ParserFormatError(input, dt.time)
+
+    hour = int(m[1])
+    if ampm := m[4]:
+        if not 1 <= hour <= 12:
+            # Cannot use 24 hour time and ampm simultaneously.
+            raise exceptions.ParserFormatError(input, dt.time)
+        if ampm == "pm" and hour != 12:
+            hour += 12
+        elif ampm == "am" and hour == 12:
+            # 12am is the 0th hour.
+            hour = 0
+
+    minute = int(m[2]) if m[2] else 0
+    second = int(m[3]) if m[3] else 0
+
+    try:
+        return dt.time(hour, minute, second)
+    except ValueError as e:
+        raise exceptions.ParserValueError(input, dt.time) from e
+
+
+_OFFSET_UNITS = {
+    "d": "days",
+    "h": "hours",
+    "m": "minutes",
+    "s": "seconds",
+}
+
+
+def offset(input: str) -> dt.timedelta:
+    """Parse `input` as a time offset, represented by a `timedelta` object."""
+    unit_pattern = rf"(\d+)([{''.join(_OFFSET_UNITS.keys())}])"
+
+    if not re.fullmatch(rf"b?({unit_pattern})+", input.lower()):
+        raise exceptions.ParserFormatError(input, dt.timedelta)
+
+    kwargs = Counter()
+    for quantity, unit_code in re.findall(unit_pattern, input.lower()):
+        unit = _OFFSET_UNITS[unit_code]
+        kwargs[unit] += int(quantity)
+
+    result = dt.timedelta(**kwargs)
+
+    if input.lower().startswith("b"):
+        # Return the backwards offset.
+        result *= -1
+
+    return result
+
+
+_ROUNDING_UNITS = {
+    "h": round.Unit.HOUR,
+    "m": round.Unit.MINUTE,
+    "s": round.Unit.SECOND,
+}
+
+
+def precision(input: str) -> round.Precision:
+    """Parse `input` as a rounding precision.
+
+    Raises `PrecisionQuantityError` instead of `ParserValueError` if the
+    precision quantity is invalid.
+    """
+    m = re.fullmatch(rf"(\d+)([{''.join(_ROUNDING_UNITS.keys())}])", input.lower())
+    if not m:
+        raise exceptions.ParserFormatError(input, round.Precision)
+
+    quantity = int(m[1])
+    unit = _ROUNDING_UNITS[m[2]]
+    return round.Precision(quantity, unit)

dstamp-3/src/dstamp/round.py

@@ -0,0 +1,88 @@
+"""Contains utilities for rounding datetime objects."""
+
+import datetime as dt
+from enum import Enum
+
+from dstamp import exceptions
+
+
+class Unit(Enum):
+    """Represents a rounding unit."""
+
+    HOUR = "hour", "h", 24
+    MINUTE = "minute", "m", 60
+    SECOND = "second", "s", 60
+
+    def __init__(self, attribute_nanme: str, code: str, max_quantity: int) -> None:
+        """Initialize a Unit instance."""
+        self.attribute_name = attribute_nanme
+        self.code = code
+        self.max_quantity = max_quantity
+
+
+class Precision:
+    """Represents a rounding precision."""
+
+    def __init__(self, quantity: int, unit: Unit) -> None:
+        """Intialize a Precision instance.
+
+        `quantity` should be a factor of `unit.max_quantity` between 1 and
+        unit.max_quantity (inclusive).
+        """
+        if (
+            quantity <= 0
+            or quantity > unit.max_quantity
+            or unit.max_quantity % quantity != 0
+        ):
+            raise exceptions.PrecisionQuantityError(quantity, unit)
+
+        self.quantity = quantity
+        self.unit = unit
+
+    def __eq__(self, other: object) -> bool:
+        """Compare equality of this Precision object with `other`."""
+        if type(other) is Precision:
+            return self.quantity == other.quantity and self.unit == other.unit
+
+        return NotImplemented
+
+
+def datetime(datetime: dt.datetime, precision: Precision) -> dt.datetime:
+    """Round `datetime` to `precision`."""
+    datetime_rounded_down = _round_down(datetime, precision)
+
+    # Find the difference between the original and the rounded-down time,
+    # and between the rounded-up time and rounded-down time.
+    difference_original_down = datetime - datetime_rounded_down
+    attr_name = precision.unit.attribute_name + "s"
+    difference_up_down = dt.timedelta(**{attr_name: precision.quantity})
+
+    # Round down if the original was less than halfway to the rounded-up time.
+    if difference_original_down < difference_up_down / 2:
+        return datetime_rounded_down
+
+    # Otherwise, round up.
+    return datetime_rounded_down + difference_up_down
+
+
+def _round_down(datetime: dt.datetime, precision: Precision) -> dt.datetime:
+    # Truncate smaller units.
+    datetime_trunacted = _truncate(datetime, precision.unit)
+
+    # Round the `precision.unit` unit down.
+    attr_name = precision.unit.attribute_name
+    value_original = getattr(datetime, attr_name)
+    value_rounded_down = value_original - value_original % precision.quantity
+
+    return datetime_trunacted.replace(**{attr_name: value_rounded_down})
+
+
+def _truncate(datetime: dt.datetime, unit: Unit) -> dt.datetime:
+    """Truncate `datetime` so that `unit` is the smallest non-zero unit."""
+    datetime_trunacted = datetime.replace(microsecond=0)
+    if unit != Unit.SECOND:
+        datetime_trunacted = datetime_trunacted.replace(second=0)
+        if unit != Unit.MINUTE:
+            datetime_trunacted = datetime_trunacted.replace(minute=0)
+
+    return datetime_trunacted

dstamp-3/src/dstamp/subcommands/__init__.py

@@ -0,0 +1,14 @@
+"""Dstamp subcommands."""
+
+import argparse
+
+from . import get, show_config
+
+
+def register_all(subparsers: argparse._SubParsersAction) -> None:
+    """Register all subcommands as subparsers."""
+    get.register(subparsers)
+    show_config.register(subparsers)
+
+
+__all__ = ["register_all"]