dstamp 1.0.0__py3-none-any.whl

dstamp/__main__.py

@@ -0,0 +1,3 @@
+from .main import app
+
+app()

dstamp/clipboard.py

@@ -0,0 +1,26 @@
+"""clipboard.py
+
+This module provides functions for interacting with the clipboard.
+"""
+
+import clipman
+
+from . import console
+
+COPY_SUCCESS_TEXT = "Copied to clipboard!"
+
+
+def copy(text: str):
+    """
+    Copy text to clipboard.
+
+    If the clipboard manager raises an error, inform the user that this is
+    the problem area and reraise the error.
+    """
+    try:
+        clipman.init()
+        clipman.set(text)
+        console.info(COPY_SUCCESS_TEXT)
+    except clipman.exceptions.ClipmanBaseException:  # pragma: no cover
+        console.error("There was a problem with the clipboard manager:")
+        raise

dstamp/config.py

@@ -0,0 +1,76 @@
+"""config.py
+
+This module contains the config file loader and parser.
+"""
+
+import tomllib
+from functools import cache
+from pathlib import Path
+
+import typer
+from pydantic import BaseModel
+
+from . import console, format
+
+APP_NAME = "dstamp"
+
+
+class DstampConfig(BaseModel):
+    copy_to_clipboard: bool = False
+    output_format: format.Format = format.Format.RELATIVE
+    round: bool = False
+    rounding_precision: str = "10m"
+
+    def __str__(self):
+        def convert_to_line(option):
+            if type(option) is str:
+                option = (option, getattr(self, option))
+            name, value = option
+            return f"{name}: {value}"
+
+        options = (
+            "copy_to_clipboard",
+            ("output_format", self.output_format.value),
+            "round",
+            "rounding_precision",
+        )
+        lines = (convert_to_line(option) for option in options)
+        return "\n".join(lines)
+
+
+@cache
+def get(config_path: Path) -> DstampConfig:
+    """Load the config file and return config object."""
+    config_path = config_path or get_config_path()
+    raw_config = _get_raw_config_from_path(config_path)
+    config = DstampConfig(**raw_config)
+    return config
+
+
+def _get_raw_config_from_path(config_path: Path) -> dict:
+    raw_config = {}
+
+    if not config_path.is_file():
+        _warn_using_default_because(f"{config_path} is not a file.")
+        return raw_config
+
+    try:
+        with open(config_path, "rb") as f:
+            raw_config = tomllib.load(f)
+    except tomllib.TOMLDecodeError:
+        _warn_using_default_because(
+            f"Config at {config_path} is not a valid TOML file."
+        )
+
+    return raw_config
+
+
+def _warn_using_default_because(reason: str) -> None:
+    console.warn(reason)
+    console.warn("Using default config settings.\n")
+
+
+def get_config_path() -> Path:  # pragma: no cover
+    # This function is patched in all our tests.
+    app_dir = typer.get_app_dir(APP_NAME)
+    return Path(app_dir) / "config.toml"

dstamp/console.py

@@ -0,0 +1,22 @@
+"""console.py
+
+This module contains functions for printing to the console.
+"""
+
+from rich.console import Console
+
+_console = Console()
+
+print = print
+
+
+def info(text: str) -> None:
+    _console.print(text, style="white")
+
+
+def warn(text: str) -> None:
+    _console.print(text, style="yellow")
+
+
+def error(text: str) -> None:
+    _console.print(text, style="bold red")

dstamp/format.py

@@ -0,0 +1,29 @@
+"""format.py
+
+This module provides tools for formatting datetimes for dstamp output.
+"""
+
+from datetime import datetime
+from enum import Enum
+
+
+class Format(str, Enum):
+    SHORT_TIME = "shorttime", "t"
+    LONG_TIME = "longtime", "T"
+    SHORT_DATE = "shortdate", "d"
+    LONG_DATE = "longdate", "D"
+    SHORT_DATETIME = "shortdatetime", "f"
+    LONG_DATETIME = "longdatetime", "F"
+    RELATIVE = "relative", "R"
+
+    def __new__(cls, value, code):
+        obj = str.__new__(cls, [value])
+        obj._value_ = value
+        obj.code = code
+        return obj
+
+
+def convert_to_discord_format(time: datetime, format: Format) -> str:
+    """Convert a datetime object into a Discord-friendly timestamp."""
+    timestamp = int(time.timestamp())
+    return f"<t:{timestamp}:{format.code}>"

dstamp/main.py

@@ -0,0 +1,211 @@
+"""main.py
+
+This module contains the commands provided by dstamp.
+"""
+
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Optional
+
+import typer
+from typing_extensions import Annotated
+
+from . import clipboard, config, console, format, parse, round
+
+app = typer.Typer(no_args_is_help=True)
+
+
+@app.callback()
+def callback():
+    """Discord Timestamp Generator."""
+
+
+FROM_CONFIG = "from config"
+
+
+@app.command("get")
+def get_timestamp(
+    time: Annotated[
+        datetime,
+        typer.Argument(
+            parser=parse.datetime_string,
+            show_default=False,
+            help="The date and time to which the timestamp should point. "
+            "If omitted, the current time is used.",
+        ),
+    ] = "",
+    offset: Annotated[
+        timedelta,
+        typer.Option(
+            "--offset",
+            "-o",
+            parser=parse.offset,
+            show_default=False,
+            help="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.",
+        ),
+    ] = "",
+    output_format: Annotated[
+        Optional[format.Format],
+        typer.Option(
+            "--output-format",
+            "-f",
+            show_default=FROM_CONFIG,
+            help="The format in which the timestamp will be displayed in Discord.",
+        ),
+    ] = None,
+    copy_to_clipboard: Annotated[
+        Optional[bool],
+        typer.Option(
+            "--copy-to-clipboard/--no-copy",
+            "-x",
+            show_default=FROM_CONFIG,
+            help="If set, copy the timestamp to clipboard. "
+            "On Linux, requires that xsel or xclip be installed.",
+        ),
+    ] = None,
+    config_path: Annotated[
+        Optional[Path],
+        typer.Option(
+            "--config",
+            "-c",
+            show_default=False,
+            exists=True,
+            dir_okay=False,
+            help="If specified, read config from this file instead of the default "
+            "location.",
+        ),
+    ] = None,
+    do_rounding: Annotated[
+        Optional[bool],
+        typer.Option(
+            "--round/--no-round",
+            "-r",
+            show_default=FROM_CONFIG,
+            help="If specified, round TIME based on --precision.",
+        ),
+    ] = None,
+    precision: Annotated[
+        Optional[str],
+        typer.Option(
+            "--precision",
+            "-p",
+            show_default=FROM_CONFIG,
+            help="The precision to which TIME will be rounded if --round is specified.",
+        ),
+    ] = None,
+):
+    """
+    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).
+    """
+    cfg = config.get(config_path)
+    output_format = fill_value(output_format, cfg.output_format)
+    do_rounding = fill_value(do_rounding, cfg.round)
+    precision = fill_value(precision, cfg.rounding_precision)
+
+    target_time = time + offset
+    if do_rounding:
+        target_time = try_round(target_time, precision)
+
+    output = format.convert_to_discord_format(target_time, output_format)
+
+    console.info(f"Using time: {round.round_time_to_precision(target_time, "1s")}.")
+    console.print(output)
+
+    copy_to_clipboard = fill_value(copy_to_clipboard, cfg.copy_to_clipboard)
+    if copy_to_clipboard:
+        clipboard.copy(output)
+
+
+def fill_value(user_provided_value, filler_value):
+    """
+    Return filler_value is user_provided value is None.
+
+    Otherwise, return user_provided_value.
+    """
+    if user_provided_value is not None:
+        return user_provided_value
+    return filler_value
+
+
+def try_round(time, precision):
+    try:
+        return round.round_time_to_precision(time, precision)
+    except round.RoundingError as e:
+        console.error(f"There was an error in rounding:\n{e.message}")
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def show_config(
+    path: Annotated[
+        Optional[Path],
+        typer.Argument(
+            show_default=False,
+            exists=True,
+            dir_okay=False,
+            help="If specified, use this config file instead of the default.",
+        ),
+    ] = None,
+):
+    """
+    Show the currently-active configuration settings and file location.
+
+    The config file should be in TOML format.
+    """
+    if path is None:
+        path = config.get_config_path()
+    console.info(f"Using config at {path}\n")
+    console.print(config.get(path))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

dstamp/parse.py

@@ -0,0 +1,225 @@
+"""parse.py
+
+This module contains parsers for datetimes and offsets.
+"""
+
+import re
+from datetime import date, datetime, time, timedelta
+
+from . import round
+
+units = {
+    "d": "days",
+    "h": "hours",
+    "m": "minutes",
+    "s": "seconds",
+}
+
+
+def offset(raw_offset: str | None) -> timedelta:
+    """
+    Parse raw_offset into a timedelta.
+
+    Accepts sequences of suboffsets consisting of an optional +/- sign,
+    a count, and a unit. Units are dhms.
+
+    Examples:
+    3d4m
+    3d-2m
+    +43h
+    -2m4s+4s-19m
+    """
+    if raw_offset is None:
+        return timedelta()
+
+    offset = timedelta()
+    subtracting = False
+    matches = re.findall(r"([+-]?)(\d+)([dhms])", raw_offset)
+    for sign, count_str, unit_key in matches:
+        subtracting = update_operation(sign, subtracting)
+        offset += get_suboffset(unit_key, count_str, subtracting)
+
+    return offset
+
+
+def update_operation(sign: str, subtracting: bool) -> bool:
+    if sign == "+":
+        return False
+    elif sign == "-":
+        return True
+    # If no sign is provided, persist the current operation.
+    return subtracting
+
+
+def get_suboffset(unit_key: str, count_str: str, subtracting: bool) -> timedelta:
+    unit = units[unit_key]
+    count = int(count_str)
+    if subtracting:
+        count *= -1
+    kwargs = {unit: count}
+    return timedelta(**kwargs)
+
+
+class ParserInputError(ValueError):
+    """Raised when there is a problem with the input received by a parser."""
+
+    def __init__(self, message=None, *args):
+        self.message = message
+        super().__init__(*args)
+
+
+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."""
+
+
+def datetime_string(raw_datetime: str) -> 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 == "":
+        return datetime.now()
+    # Ensure there is both a date and time supplied.
+    if (x := raw_datetime.count(",")) == 0:
+        try:
+            return datetime_string("today," + raw_datetime)
+        except InvalidFormatError:
+            return datetime_string(raw_datetime + ",midnight")
+    elif x >= 2:
+        raise InvalidFormatError
+
+    datestr, timestr = raw_datetime.split(",")
+    parsed_date = parse_date(datestr)
+    parsed_time = parse_time(timestr)
+    timezone = datetime.now().tzinfo
+    return datetime.combine(parsed_date, parsed_time, timezone)
+
+
+def parse_date(datestr: str) -> date:
+    if datestr == "today":
+        return date.today()
+
+    if datestr in ("tmrw", "tomorrow"):
+        return date.today() + timedelta(days=1)
+
+    if datestr == "yesterday":
+        return date.today() - 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 date.today().year
+
+    try:
+        return date(year, month, day)
+    except ValueError as e:
+        raise InvalidValueError from e
+
+
+def parse_time(timestr: str) -> time:
+    if timestr == "now":
+        return datetime.now().time()
+
+    if timestr == "midnight":
+        return time()
+
+    if timestr == "noon":
+        return 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 > 12:
+        # Disallow noonstrings with 24h format.
+        raise InvalidFormatError
+
+    if noonstr == "pm":
+        hour += 12
+
+    try:
+        return 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
+
+
+def rounding_precision(raw_precision: str) -> tuple[int, str]:
+    """
+    Accepts precisions in the format of <value><unit>
+    """
+    lowercase_input = raw_precision.lower()
+
+    for unit in round.RoundingUnit:
+        m = re.fullmatch(rf"(\d*){unit.code}", lowercase_input)
+        if m is None:
+            continue
+
+        quantity = int(m[1]) if m[1] else 1
+
+        quantity_is_in_range = 0 < quantity < unit.max_quantity
+        quantity_is_a_factor_of_max = (
+            quantity != 0 and unit.max_quantity % quantity == 0
+        )
+        if not (quantity_is_in_range and quantity_is_a_factor_of_max):
+            raise InvalidValueError(
+                "Invalid precision quantity: "
+                f"[underline cyan]{quantity}[/]{unit.code}. "
+                f"Quantity must be between 0 and {unit.max_quantity} (exclusive), "
+                f"and must be a factor of {unit.max_quantity}."
+            )
+
+        return quantity, unit
+
+    raise InvalidFormatError(f"Invalid precision: {raw_precision}.")

dstamp/round.py

@@ -0,0 +1,59 @@
+"""round.py
+
+This module contains logic for rounding timestamps to nicer ones.
+"""
+
+from datetime import datetime, timedelta
+from enum import Enum
+
+from . import parse
+
+
+class RoundingError(ValueError):
+    """Raised when a rounding attempt fails."""
+
+    def __init__(self, message=None, *args):
+        self.message = message
+        super().__init__(*args)
+
+
+class RoundingUnit(Enum):
+    HOUR = "hour", "h", 24
+    MINUTE = "minute", "m", 60
+    SECOND = "second", "s", 60
+
+    def __init__(self, attribute_name, code, max_quantity):
+        self.attribute_name = attribute_name
+        self.code = code
+        self.max_quantity = max_quantity
+
+
+def round_time_to_precision(time: datetime, precision: str):
+    try:
+        quantity, unit = parse.rounding_precision(precision)
+    except parse.ParserInputError as e:
+        raise RoundingError(e.message) from e
+
+    truncated_time = time.replace(microsecond=0)
+    if unit is not RoundingUnit.SECOND:
+        truncated_time = truncated_time.replace(second=0)
+        if unit is not RoundingUnit.MINUTE:
+            truncated_time = truncated_time.replace(minute=0)
+
+    # This is currently very crude as it only checks the top-most unit.
+    # This means it may not handle values close to half-way as expected.
+    initial_value = getattr(time, unit.attribute_name)
+    rounded_value = round_int_to_precision(initial_value, quantity)
+
+    # Use timedelta to handle the case where the rounded value is equal to the
+    # maximum quantity, eg. if we need to round up to the next day.
+    return truncated_time.replace(**{unit.attribute_name: 0}) + timedelta(
+        **{f"{unit.attribute_name}s": rounded_value}
+    )
+
+
+def round_int_to_precision(value: int, precision: int) -> int:
+    scaled_value = float(value) / precision
+    rounded_scaled_value = int(round(scaled_value))
+    rounded_value = rounded_scaled_value * precision
+    return rounded_value

dstamp-1.0.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mariusz Tang
+
+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.

dstamp-1.0.0.dist-info/METADATA

@@ -0,0 +1,79 @@
+Metadata-Version: 2.3
+Name: dstamp
+Version: 1.0.0
+Summary: CLI app for generating timestamps for use in Discord chats.
+License: MIT
+Keywords: discord,timestamp,generator
+Author: Mariusz Tang
+Author-email: dev@mariusztang.com
+Requires-Python: >=3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Topic :: Communications :: Chat
+Classifier: Environment :: Console
+Requires-Dist: clipman (>=3.3.1,<4.0.0)
+Requires-Dist: pydantic (>=2.11.7,<3.0.0)
+Requires-Dist: typer (>=0.16.0,<0.17.0)
+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.
+
+## 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 -o 2h --round --precision h
+
+# Copy to clipboard
+dstamp --copy-to-clipboard
+
+# Show active configuration
+dstamp show-config
+```
+
+For full documentation see the help messages:
+
+```bash
+dstamp --help
+dstamp get --help
+dstamp show-config --help
+```
+
+## Configuration
+
+Run `show-config` with no arguments to find the default config location:
+
+```bash
+dstamp show-config
+```
+
+The config file should be in `.toml` format. The defaults are equivalent to the
+following:
+
+```toml
+copy_to_clipboard = false
+output_format = "relative"
+round = false
+rounding_precision = "10m"
+```
+
+These settings will be in effect unless overriden by CLI options.
+
+## 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-1.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+dstamp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dstamp/__main__.py,sha256=6Hs2PV7EYc5Tid4g4OtcLXhqVHiNYTGzSBdoOnW2HXA,29
+dstamp/clipboard.py,sha256=4zkRfRvYb6L4FJL6l70im_oCXR5ffP13HcAfQLL2LUk,615
+dstamp/config.py,sha256=ECEIeVPRlq4V3IXiOv9Oa_mPgK6xXm_yZbYPZUxgyHY,1993
+dstamp/console.py,sha256=lDwOqmaayRyou9OJvPggBsz-X1bH3GOZP652_v4Elt0,368
+dstamp/format.py,sha256=F-D46RAb6E4CVn-lzfvWGvle83DE6qp7_e72SCLWCc8,786
+dstamp/main.py,sha256=Yjb6Vf-9ofVCgSslDrq7Bs5ag5VzP5SJWYpV2Y83LMM,6180
+dstamp/parse.py,sha256=EQPMDdTL7UUqjcPus_6hIsmRUeh_6_9QMqnkInICZzU,5769
+dstamp/round.py,sha256=5dyK4T7LaoSd9yuNyeYqWSB57SAyzruRDXi-k9YpnuE,1912
+dstamp-1.0.0.dist-info/LICENSE,sha256=K9oI2B5w9TbYBLlh6p35IPz59zRh4gWnY9I5rKFoQb4,1069
+dstamp-1.0.0.dist-info/METADATA,sha256=aMKr22eyHszzEB2F1SAMJZePb25BCDV95iUDh0ukdmw,1840
+dstamp-1.0.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+dstamp-1.0.0.dist-info/entry_points.txt,sha256=XLxBMWrm64JnP_nEcVwl1fXfC0j7tki81W7hhcqrzHI,42
+dstamp-1.0.0.dist-info/RECORD,,

dstamp-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.1.3
+Root-Is-Purelib: true
+Tag: py3-none-any

dstamp-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+dstamp=dstamp.main:app
+