dstamp 1.0.0__tar.gz → 2__tar.gz

dstamp-2/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: dstamp
+Version: 2
+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: cyclopts>=4.11.0
+Requires-Dist: platformdirs>=4.9.6
+Requires-Dist: pyperclip>=1.11.0
+Requires-Dist: pytest-mock>=3.15.1
+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.
+
+## TODO
+
+I intend to rewrite this project to use the standard argparse library instead
+of cyclopts. This makes the whole typer-to-cyclopts migration seem rather silly.
+My reasoning is that cyclopts is a bit too heavy-handed for my tastes, and I
+prefer how argparse forces you to separate parsing from handling functions.
+
+## 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/
+
+## Example usage
+
+```bash
+# For the current time
+dstamp get
+
+# Two hours in the future
+dstamp get --offset 2h
+
+# Round to the nearest hour
+dstamp get --offset 2h --round --precision h
+
+# Copy to clipboard
+dstamp --copy-to-clipboard
+```
+
+For full documentation see the help messages:
+
+```bash
+dstamp --help
+dstamp get --help
+```
+
+## Configuration
+
+dstamp accepts a TOML configuration file which can override any command-line
+argument. Keys should be structured as `command.option`. For example, to enable
+rounding by default and set a custom default rounding precision for the `get`
+command, you could do the following:
+
+```toml
+[get]
+round = true
+precision = "15m"
+```
+
+Use the `show-config` command to find the default config location. Specify the
+`--config` flag to use a different file.
+
+```bash
+dstamp show-config
+dstamp --config ./path-to-a-different-file.toml
+```
+
+## Versioning
+
+This project uses an `X.Y` versioning scheme. Bugfixes will move the version to
+`X.Y+1`, and anything else will move it to `X+1.0`. If `Y` is 0, we omit it,
+so `X+1.0` actually just becomes `X+1`.
+
+## 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/README.md

@@ -0,0 +1,82 @@
+# dstamp
+
+CLI app for generating timestamps for use in Discord chats.
+
+## TODO
+
+I intend to rewrite this project to use the standard argparse library instead
+of cyclopts. This makes the whole typer-to-cyclopts migration seem rather silly.
+My reasoning is that cyclopts is a bit too heavy-handed for my tastes, and I
+prefer how argparse forces you to separate parsing from handling functions.
+
+## 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/
+
+## Example usage
+
+```bash
+# For the current time
+dstamp get
+
+# Two hours in the future
+dstamp get --offset 2h
+
+# Round to the nearest hour
+dstamp get --offset 2h --round --precision h
+
+# Copy to clipboard
+dstamp --copy-to-clipboard
+```
+
+For full documentation see the help messages:
+
+```bash
+dstamp --help
+dstamp get --help
+```
+
+## Configuration
+
+dstamp accepts a TOML configuration file which can override any command-line
+argument. Keys should be structured as `command.option`. For example, to enable
+rounding by default and set a custom default rounding precision for the `get`
+command, you could do the following:
+
+```toml
+[get]
+round = true
+precision = "15m"
+```
+
+Use the `show-config` command to find the default config location. Specify the
+`--config` flag to use a different file.
+
+```bash
+dstamp show-config
+dstamp --config ./path-to-a-different-file.toml
+```
+
+## Versioning
+
+This project uses an `X.Y` versioning scheme. Bugfixes will move the version to
+`X.Y+1`, and anything else will move it to `X+1.0`. If `Y` is 0, we omit it,
+so `X+1.0` actually just becomes `X+1`.
+
+## 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/pyproject.toml

@@ -0,0 +1,83 @@
+[project]
+name = "dstamp"
+version = "2"
+description = "CLI app for generating timestamps for use in Discord chats."
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+authors = [{ name = "Mariusz Tang", email = "dev@mariusztang.com" }]
+keywords = ["discord", "generator", "timestamp"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+  "Topic :: Communications :: Chat",
+]
+dependencies = [
+  "cyclopts>=4.11.0",
+  "platformdirs>=4.9.6",
+  "pyperclip>=1.11.0",
+  "pytest-mock>=3.15.1",
+]
+
+[project.urls]
+Issues = "https://github.com/mariusz-tang/dstamp/issues"
+Repository = "https://github.com/mariusz-tang/dstamp"
+
+[project.scripts]
+dstamp = "dstamp.main:app.meta"
+
+[dependency-groups]
+dev = [
+  "coverage>=7.13.5",
+  "freezegun>=1.5.5",
+  "pytest>=9.0.3",
+  "ty>=0.0.34",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.8,<0.12"]
+build-backend = "uv_build"
+
+[tool.coverage.run]
+branch = true
+command_line = "-m pytest"
+source = ["src/"]
+omit = ["src/dstamp/__main__.py", "src/dstamp/console.py"]
+
+[tool.coverage.report]
+skip_empty = true
+skip_covered = true
+
+[tool.coverage.html]
+skip_empty = true
+skip_covered = true
+
+[tool.pytest]
+addopts = ["--import-mode=importlib"]
+strict = true
+
+[tool.ruff.lint]
+select = [
+  "ANN",  # flake8-annotations
+  "ARG",  # flake8-unused-arguments
+  "B",  # flake8-bugbear
+  "C4",  # flake8-comprehensions
+  "C90",  # mccabe
+  "E",  # pycodestyle error
+  "F",  # pyflakes
+  "FURB",  # refurb
+  "I",  # isort
+  "N",  # pep8-naming
+  "PT",  # flake8-pytest-style
+  "PTH",  # flake8-use-pathlib
+  "RET",  # flake8-return
+  "RSE",  # flake8-raise
+  "SIM",  # flake8-simplify
+  "SLF",  # flake8-self
+  "TRY",  # tryceratops
+  "UP",  # pyupgrade
+  "W",  # pycodestyle warning
+]
+ignore = ["TRY003"]  # This rule is too strict, especially for ValueError.
+flake8-pytest-style.parametrize-names-type = "csv"

dstamp-2/src/dstamp/__main__.py

@@ -0,0 +1,5 @@
+"""Executes the app."""
+
+from dstamp.main import app
+
+app.meta()

dstamp-2/src/dstamp/config.py

@@ -0,0 +1,12 @@
+"""Config file utilities."""
+
+from pathlib import Path
+
+import platformdirs
+
+APP_NAME = "dstamp"
+
+
+def get_config_path() -> Path:
+    app_dir = platformdirs.user_config_path(APP_NAME, ensure_exists=True)
+    return app_dir / "config.toml"

{dstamp-1.0.0 → dstamp-2/src}/dstamp/console.py

@@ -1,11 +1,8 @@
-"""console.py
-
-This module contains functions for printing to the console.
-"""
+"""Console printing utilities."""
 
 from rich.console import Console
 
-_console = Console()
+_console = Console(highlight=False)
 
 print = print
 

dstamp-2/src/dstamp/format.py

@@ -0,0 +1,24 @@
+"""Datetime formatting utilities."""
+
+from datetime import datetime
+from enum import StrEnum
+
+
+class Format(StrEnum):
+    SHORT_TIME = "t"
+    LONG_TIME = "T"
+    SHORT_DATE = "d"
+    LONG_DATE = "D"
+    SHORT_DATETIME = "f"
+    LONG_DATETIME = "F"
+    RELATIVE = "R"
+
+
+def human_readable(time: datetime) -> str:
+    return time.strftime("%I:%M:%S on %B %d, %Y")
+
+
+def discord(time: datetime, format: Format) -> str:
+    """Convert a datetime object into a Discord-friendly timestamp."""
+    timestamp = int(time.timestamp())
+    return f"<t:{timestamp}:{format.value}>"

dstamp-2/src/dstamp/main.py

@@ -0,0 +1,172 @@
+"""CLI commands."""
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Annotated
+
+import cyclopts.config
+import pyperclip
+from cyclopts import App, Parameter
+
+from dstamp import config, console, format, parse
+from dstamp.round import Precision, time_to_precision
+
+app = App(help="Discord timestamp generator")
+app.register_install_completion_command(add_to_startup=False)
+
+COPY_SUCCESS_TEXT = "Copied to clipboard!"
+
+
+@app.meta.default
+def launch_with_config_file(
+    *tokens: Annotated[str, Parameter(show=False, allow_leading_hyphen=True)],
+    config_path: Annotated[Path | None, Parameter("config")] = None,
+) -> int:
+    """
+    Launch the application with a config file.
+
+    :param config_path: Alternate configuration file path.
+    """
+    if config_path is None:
+        config_path = config.get_config_path()
+    app.config = cyclopts.config.Toml(config_path)
+    return app(tokens)
+
+
+@app.command(name="get")
+def get_timestamp(
+    time: str | None = None,
+    /,
+    *,
+    offset: Annotated[str | None, Parameter(alias="-o")] = None,
+    output_format: Annotated[
+        format.Format, Parameter(alias="-f")
+    ] = format.Format.RELATIVE,
+    copy_to_clipboard: Annotated[bool, Parameter(alias="-x")] = False,
+    round: Annotated[bool, Parameter(alias="-r")] = False,
+    precision: Annotated[str, Parameter(alias="-p")] = "10m",
+) -> int:
+    r"""
+    Generate a Discord timestamp.
+
+    If TIME is omitted, uses the current time.
+
+    TIME should be of the form \<date>,\<time>.
+    Either \<date> or \<time> can be omitted, in which case you should omit the
+    comma as well.
+
+    \<date> should be of the following form: ddmmmyyyy.
+
+    dd and yyyy should be numbers.
+
+    mmm should be at least the first three letters of the month. For instance,
+    for August you can specify aug, augu, augus, or august.
+
+    You can omit the year to specify the current year. You can omit \<date>
+    entirely to specify the current date.
+
+    The command will also accept the following special values:
+    - today
+    - tmrw (tomorrow)
+    - tomorrow
+    - yesterday
+
+    \<time> should be of the following form: hhmmss(am/pm).
+
+    You can omit seconds to specify 0. If you do, you can omit minutes to specify
+    0 as well. If you omit (am/pm), 24-hour time will be used. You can omit \<time>
+    entirely to specify midnight.
+
+    If you omit both \<date> and \<time>, the current date and time will be used.
+
+    The command will also accept the following special values:
+    now (the current time, but not necessarily the current date),
+    midnight,
+    noon.
+
+    Examples:
+    - 5jun,1pm (5th June of the current year, 1:00pm)
+    - 8january2025,1530 (8th January 2025, 3:30pm)
+    - 25nov2000,13002pm (25th November 2000, 1:30:02pm)
+    - 1jan (1st January of the current year, midnight)
+    - 7feb2023,15 (7th February 2023, 3:00pm)
+    - 5 (the current date, 5:00am)
+    - 0 (the current date, midnight)
+    - tmrw,now (tomorrow, the current time, ie. 24 hours from the current time)
+    - tmrw (tomorrow, midnight)
+
+    :param time: The date and time to which the timestamp should point. If
+    omitted, the current time is used.
+    :param offset: Optional offset to apply to TIME. Optional offset to apply
+    to TIME. Examples: 2d3h1m, +3s, -3d+1d, 3m-3h2h. The only acceptable units
+    are d(ays), h(ours), m(inutes), and s(econds). Subtraction applies to all
+    times after the - until the next +. Units can be repeated.
+    :param output_format: The format in which the timestamp will be displayed
+    in Discord.
+    :param copy_to_clipboard: If set, copy the timestamp to clipboard. On Linux,
+    requires that xsel or xclip be installed.
+    :param do_rounding: If specified, round TIME based on PRECISION.
+    :param precision: The precision to which TIME will be rounded if ROUND is
+    specified.
+    """
+    time_obj = try_parse(parse.datetime, time, "datetime")
+    time_delta = try_parse(parse.offset, offset, "offset")
+
+    if time_obj is None or time_delta is None:
+        return 1
+
+    time_obj = time_delta + time_obj
+
+    console.info(f"Using time: {format.human_readable(time_obj)}.")
+
+    if round:
+        try:
+            precision: Precision = parse.rounding_precision(precision)
+        except parse.ParserInputError as e:
+            console.error(str(e))
+            return 1
+        time_obj = time_to_precision(time_obj, precision)
+        console.info(f"After rounding: {format.human_readable(time_obj)}.")
+
+    output = format.discord(time_obj, output_format)
+
+    console.print(output)
+
+    if copy_to_clipboard:
+        try:
+            pyperclip.copy(output)
+            console.info(COPY_SUCCESS_TEXT)
+        except pyperclip.PyperclipException as e:
+            console.error(f"There was a problem with the clipboard manager:{e}")
+            return 1
+
+    return 0
+
+
+@app.command
+def show_config() -> int:
+    """Show the default config location."""
+    print(config.get_config_path())
+    return 0
+
+
+def try_parse[T](
+    parser: Callable[[str | None], T], raw_input: str | None, quantity_type: str
+) -> T | None:
+    """Attempt to parse a quantity, printing an error message on failure.
+
+    :param parser: Parsing function to use.
+    :param raw_input: Input string to parse.
+    :param quantity_type: Type of quantity being parsed. Used in the error
+    message.
+
+    :returns: The parsed quantity, or None on failure.
+    """
+    try:
+        return parser(raw_input)
+    except parse.InvalidFormatError:
+        console.error(f"{raw_input} could not be parsed as a {quantity_type}.")
+    except parse.InvalidValueError:
+        console.error(f"{raw_input} represents an invalid {quantity_type}.")
+
+    return None

dstamp-2/src/dstamp/parse/__init__.py

@@ -0,0 +1,15 @@
+"""Provides input parsers for various types."""
+
+from .datetime import datetime
+from .exceptions import InvalidFormatError, InvalidValueError, ParserInputError
+from .offset import offset
+from .precision import rounding_precision
+
+__all__ = [
+    "datetime",
+    "InvalidFormatError",
+    "InvalidValueError",
+    "ParserInputError",
+    "offset",
+    "rounding_precision",
+]

dstamp-2/src/dstamp/parse/datetime.py

@@ -0,0 +1,127 @@
+"""Provides input parsers for dates and times."""
+
+import datetime as dt
+import re
+
+from .exceptions import InvalidFormatError, InvalidValueError
+
+
+def datetime(raw_datetime: str | None) -> dt.datetime:
+    """
+    Parse raw_datetime into a datetime.
+
+    raw_datetime should be of the form "ddmmmyyyy,hhmmss", albeit with some
+    flexibility and special values allowed.
+
+    If the date is omitted, use the current date.
+    If the only time is omitted, use midnight.
+    If both are omitted, use the current date and time.
+
+    Valid examples:
+    07jun2025,1230
+    9august,330pm
+    today,now
+    tomorrow
+    12pm
+    73002pm
+    noon
+    midnight
+    """
+    if raw_datetime is None or raw_datetime == "":
+        return dt.datetime.now().replace(microsecond=0)
+    # Ensure there is both a date and time supplied.
+    if (x := raw_datetime.count(",")) == 0:
+        try:
+            return datetime("today," + raw_datetime)
+        except InvalidFormatError:
+            return datetime(raw_datetime + ",midnight")
+    elif x >= 2:
+        raise InvalidFormatError
+
+    datestr, timestr = raw_datetime.split(",")
+    parsed_date = _date(datestr)
+    parsed_time = _time(timestr).replace(microsecond=0)
+    timezone = dt.datetime.now().tzinfo
+    return dt.datetime.combine(parsed_date, parsed_time, timezone)
+
+
+def _date(datestr: str) -> dt.date:
+    if datestr == "today":
+        return dt.date.today()
+
+    if datestr in ("tmrw", "tomorrow"):
+        return dt.date.today() + dt.timedelta(days=1)
+
+    if datestr == "yesterday":
+        return dt.date.today() - dt.timedelta(days=1)
+
+    m = re.fullmatch(r"(\d{1,2})([a-zA-Z]{3,})(\d*)", datestr)
+    if m is None:
+        raise InvalidFormatError
+
+    day = int(m[1])
+    month = _get_month_from_shortening(m[2].lower())
+    year = int(m[3]) if m[3] else dt.date.today().year
+
+    try:
+        return dt.date(year, month, day)
+    except ValueError as e:
+        raise InvalidValueError from e
+
+
+def _time(timestr: str) -> dt.time:
+    if timestr == "now":
+        return dt.datetime.now().time()
+
+    if timestr == "midnight":
+        return dt.time()
+
+    if timestr == "noon":
+        return dt.time(12)
+
+    m = re.fullmatch(r"(\d{1,2}?)(\d{2})?(\d{2})?([ap]m)?", timestr)
+    if m is None:
+        raise InvalidFormatError
+
+    hour = int(m[1])
+    minute = int(m[2]) if m[2] else 0
+    second = int(m[3]) if m[3] else 0
+    noonstr = m[4]
+
+    if noonstr is not None and (hour == 0 or hour > 12):
+        # Disallow noonstrings with 24h format.
+        raise InvalidFormatError
+
+    if noonstr == "pm" and hour != 12:
+        hour += 12
+    elif noonstr == "am" and hour == 12:
+        hour = 0
+
+    try:
+        return dt.time(hour, minute, second)
+    except ValueError as e:
+        raise InvalidValueError from e
+
+
+_months = [
+    "january",
+    "february",
+    "march",
+    "april",
+    "may",
+    "june",
+    "july",
+    "august",
+    "september",
+    "october",
+    "november",
+    "december",
+]
+
+
+def _get_month_from_shortening(shortening: str) -> int:
+    """Returns the index of the first month which starts with the given string."""
+    for ix, name in enumerate(_months):
+        if name.startswith(shortening):
+            return ix + 1
+    raise InvalidFormatError

dstamp-2/src/dstamp/parse/exceptions.py

@@ -0,0 +1,13 @@
+"""Parsing-related exceptions."""
+
+
+class ParserInputError(ValueError):
+    """Raised when there is a problem with the input received by a parser."""
+
+
+class InvalidFormatError(ParserInputError):
+    """Raised when a parser is provided an improperly-formatted value."""
+
+
+class InvalidValueError(ParserInputError):
+    """Raised when a parser is provided a correctly-formatted but invalid value."""