birthdays-cli 0.1.0__tar.gz

birthdays_cli-0.1.0/.gitignore

@@ -0,0 +1,223 @@
+# Local tests
+tests/untracked
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

birthdays_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Volodymyr Horshenin
+
+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.

birthdays_cli-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: birthdays-cli
+Version: 0.1.0
+Summary: A command-line utility for displaying and managing birthdays from JSON- or vCard-based contacts.
+Project-URL: Repository, https://github.com/l1asis/birthdays.git
+Project-URL: Issues, https://github.com/l1asis/birthdays/issues
+Author: Volodymyr Horshenin
+License-Expression: MIT
+License-File: LICENSE
+Keywords: address-book,birthday-tracker,birthdays,calendar,cli,command-line,contacts,vcard,vcf
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: python-dateutil>=2.8.2
+Description-Content-Type: text/markdown
+
+# birthdays
+
+![birthdays GIF demo](https://raw.githubusercontent.com/l1asis/birthdays/refs/heads/main/examples/demo.gif)
+
+[![PyPI Version](https://img.shields.io/pypi/v/birthdays-cli.svg)](https://pypi.org/project/birthdays-cli/)
+[![PyPI Python version](https://img.shields.io/pypi/pyversions/birthdays-cli.svg)](https://pypi.org/project/birthdays-cli/)
+![PyPI downloads](https://img.shields.io/pypi/dm/birthdays-cli)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+`birthdays` is a robust Python command-line tool designed to conveniently manage, track, and celebrate your contacts' birthdays.
+
+## Features
+
+- **Customizable Sorting:** List birthdays exactly how you want to see them (by upcoming, recent, age, name, or date)
+- **CRUD Operations:** Easily `add`, `edit`, and `delete` entries. The deletion and edit commands feature a convenient fuzzy search so you don't have to type out exact names
+- **Smart Imports:** Import contacts directly from `.vcf` vCard files or JSON databases
+- **Interactive Merging:** During imports, the CLI intelligently detects duplicates or data collisions and prompts you to safely merge them
+- **Leapling Support:** Configure how leap year birthdays (February 29th) are handled in non-leap years, choosing to celebrate either the day before or the day after
+- **Festive UI:** Every date is assigned a unique, deterministic emoji to keep the terminal vibe bright and colorful
+
+## Requirements
+
+- Python 3.11+
+
+## Installation
+
+Install the package from PyPI using your favorite package management tool such as pip, pipx, or uv:
+
+```bash
+pip install birthdays-cli
+```
+
+Or install the latest version from source:
+
+```bash
+git clone https://github.com/l1asis/birthdays.git
+cd birthdays
+pip install .
+```
+
+## Usage
+
+`birthdays` uses simple subcommands to organize different operations. You can append `--help` to any command to see its available arguments.
+
+### Listing Birthdays
+
+> [!NOTE]
+> By default, this sorts by upcoming birthdays in descending order so the most immediate celebrations are right at your cursor.
+
+```bash
+birthdays list
+```
+
+**Options:**
+
+- `--sort`: Choose from `name`, `date`, `upcoming`, `recent`, or `age`.
+- `--order`: Choose `asc` or `desc`.
+- `-f`, `--file`: Temporarily read and display birthdays directly from a `.vcf` or `.json` file without modifying your local database.
+
+### Adding an Entry
+
+> [!NOTE]
+> The date can be formatted as `YYYY-MM-DD`, or simply `MM-DD` if the year is unknown.
+
+```bash
+birthdays add "John Doe" 1990-05-14 --note "Loves chocolate cake"
+```
+
+### Editing an Entry
+
+> [!NOTE]
+> You can use either the name or UUID. You only need to pass the flags for the specific data you want to change.
+
+```bash
+birthdays edit "John Doe" --date 1991-05-14
+```
+
+### Deleting an Entry
+
+> [!TIP]
+> The CLI uses fuzzy matching, so typing a partial name usually works! Append `-y` to skip the confirmation prompt.
+
+```bash
+birthdays delete "John Doe"
+```
+
+### Importing Contacts
+
+> [!TIP]
+> The interactive prompt will guide you through any data collisions. Append `-y` to automatically skip these prompts and blindly merge safe entries.
+
+```bash
+birthdays import ./contacts.vcf
+```
+
+## Contributing
+
+Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
+
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feat/amazing-feature`)
+3. Commit your Changes (`git commit -m 'feat: ✨ add some amazing-feature'`)
+4. Push to the Branch (`git push origin feat/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+Distributed under the MIT License. See `LICENSE` for more information.

birthdays_cli-0.1.0/README.md

@@ -0,0 +1,109 @@
+# birthdays
+
+![birthdays GIF demo](https://raw.githubusercontent.com/l1asis/birthdays/refs/heads/main/examples/demo.gif)
+
+[![PyPI Version](https://img.shields.io/pypi/v/birthdays-cli.svg)](https://pypi.org/project/birthdays-cli/)
+[![PyPI Python version](https://img.shields.io/pypi/pyversions/birthdays-cli.svg)](https://pypi.org/project/birthdays-cli/)
+![PyPI downloads](https://img.shields.io/pypi/dm/birthdays-cli)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+`birthdays` is a robust Python command-line tool designed to conveniently manage, track, and celebrate your contacts' birthdays.
+
+## Features
+
+- **Customizable Sorting:** List birthdays exactly how you want to see them (by upcoming, recent, age, name, or date)
+- **CRUD Operations:** Easily `add`, `edit`, and `delete` entries. The deletion and edit commands feature a convenient fuzzy search so you don't have to type out exact names
+- **Smart Imports:** Import contacts directly from `.vcf` vCard files or JSON databases
+- **Interactive Merging:** During imports, the CLI intelligently detects duplicates or data collisions and prompts you to safely merge them
+- **Leapling Support:** Configure how leap year birthdays (February 29th) are handled in non-leap years, choosing to celebrate either the day before or the day after
+- **Festive UI:** Every date is assigned a unique, deterministic emoji to keep the terminal vibe bright and colorful
+
+## Requirements
+
+- Python 3.11+
+
+## Installation
+
+Install the package from PyPI using your favorite package management tool such as pip, pipx, or uv:
+
+```bash
+pip install birthdays-cli
+```
+
+Or install the latest version from source:
+
+```bash
+git clone https://github.com/l1asis/birthdays.git
+cd birthdays
+pip install .
+```
+
+## Usage
+
+`birthdays` uses simple subcommands to organize different operations. You can append `--help` to any command to see its available arguments.
+
+### Listing Birthdays
+
+> [!NOTE]
+> By default, this sorts by upcoming birthdays in descending order so the most immediate celebrations are right at your cursor.
+
+```bash
+birthdays list
+```
+
+**Options:**
+
+- `--sort`: Choose from `name`, `date`, `upcoming`, `recent`, or `age`.
+- `--order`: Choose `asc` or `desc`.
+- `-f`, `--file`: Temporarily read and display birthdays directly from a `.vcf` or `.json` file without modifying your local database.
+
+### Adding an Entry
+
+> [!NOTE]
+> The date can be formatted as `YYYY-MM-DD`, or simply `MM-DD` if the year is unknown.
+
+```bash
+birthdays add "John Doe" 1990-05-14 --note "Loves chocolate cake"
+```
+
+### Editing an Entry
+
+> [!NOTE]
+> You can use either the name or UUID. You only need to pass the flags for the specific data you want to change.
+
+```bash
+birthdays edit "John Doe" --date 1991-05-14
+```
+
+### Deleting an Entry
+
+> [!TIP]
+> The CLI uses fuzzy matching, so typing a partial name usually works! Append `-y` to skip the confirmation prompt.
+
+```bash
+birthdays delete "John Doe"
+```
+
+### Importing Contacts
+
+> [!TIP]
+> The interactive prompt will guide you through any data collisions. Append `-y` to automatically skip these prompts and blindly merge safe entries.
+
+```bash
+birthdays import ./contacts.vcf
+```
+
+## Contributing
+
+Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
+
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feat/amazing-feature`)
+3. Commit your Changes (`git commit -m 'feat: ✨ add some amazing-feature'`)
+4. Push to the Branch (`git push origin feat/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+Distributed under the MIT License. See `LICENSE` for more information.

birthdays_cli-0.1.0/examples/contacts.vcf

@@ -0,0 +1,56 @@
+BEGIN:VCARD
+VERSION:3.0
+FN:Amélie Laurent
+BDAY:1990-05-14
+NOTE:Met at the UX conference in Paris. Always brings great coffee.
+END:VCARD
+
+BEGIN:VCARD
+VERSION:3.0
+FN:Hiroshi Tanaka
+BDAY:1992-02-29
+NOTE:University roommate. Leapling! 🐸
+END:VCARD
+
+BEGIN:VCARD
+VERSION:3.0
+FN;CHARSET=UTF-8;ENCODING=QUOTED-PRINTABLE:=D0=94=D1=96=D0=B4=D1=83=D1=81=D1=8C =D0=86=D0=B2=D0=B0=D0=BD
+BDAY:1955-01-07
+NOTE;CHARSET=UTF-8;ENCODING=QUOTED-PRINTABLE:The absolute best grandfather.=20=
+Always tells the greatest stories about his youth.
+END:VCARD
+
+BEGIN:VCARD
+VERSION:3.0
+FN:María José García
+BDAY:--10-31
+NOTE:Halloween birthday party organizer.
+END:VCARD
+
+BEGIN:VCARD
+VERSION:3.0
+FN:Fatima Al-Sayed
+BDAY:1988-08-12
+NOTE:Project manager for the backend migration.
+  Needs to be reminded about the server timezone changes.
+END:VCARD
+
+BEGIN:VCARD
+VERSION:3.0
+FN:Kwame Osei
+BDAY:--03-15
+NOTE:Gym buddy.
+END:VCARD
+
+BEGIN:VCARD
+VERSION:3.0
+FN:Mateusz Kowalski
+BDAY:1995-11-11
+NOTE:Brings the best pierogi to the office potlucks.
+END:VCARD
+
+BEGIN:VCARD
+VERSION:3.0
+FN:Priya Sharma
+BDAY:1999-07-21
+END:VCARD

birthdays_cli-0.1.0/examples/demo.tape

@@ -0,0 +1,59 @@
+# Output settings
+Output examples/demo.gif
+Set FontSize 15
+Set Width 915
+Set Height 600
+Set Padding 30
+Set Theme "Dracula"
+Set WindowBar Colorful
+
+# Hidden setup
+Hide
+Type "export DEBIAN_FRONTEND=noninteractive"
+Enter
+
+# Install base requirements
+# DEBUG: "> examples/setup.log 2>&1"
+Type "apt update && apt install -y python3 python3-pip python3-venv"
+Enter
+Sleep 60s
+
+# Download the Charm's gum
+Type "apt update && apt -y install gum"
+Enter
+Sleep 45s
+
+# Install the birthdays package
+Type "pip3 install . --break-system-packages"
+Enter
+Sleep 15s
+
+Type "clear"
+Enter
+Show
+
+# Show the fake contacts data
+Type "gum pager < examples/contacts.vcf"
+Sleep 500ms
+Enter
+Sleep 500ms
+
+# Scroll down to view more contacts
+Down@40ms 35
+Sleep 500ms
+
+# Exit the pager so we can run commands again
+Type "q"
+Sleep 500ms
+
+# Run the import command
+Type "birthdays import examples/contacts.vcf"
+Sleep 500ms
+Enter
+Sleep 1s
+
+# Show the list view
+Type "birthdays list --sort upcoming"
+Sleep 500ms
+Enter
+Sleep 6s

birthdays_cli-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "birthdays-cli"
+version = "0.1.0"
+dependencies = [
+    "python-dateutil>=2.8.2",
+    "platformdirs>=4.0.0",
+]
+requires-python = ">=3.11"
+authors = [
+  {name = "Volodymyr Horshenin"}
+]
+description = "A command-line utility for displaying and managing birthdays from JSON- or vCard-based contacts."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+keywords = [
+    "cli", "command-line", "birthdays", "birthday-tracker",
+    "contacts", "vcard", "vcf", "calendar", "address-book"
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+
+  "Intended Audience :: End Users/Desktop",
+  "Topic :: Utilities",
+  "Environment :: Console",
+
+  "Operating System :: OS Independent",
+
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+
+[project.urls]
+Repository = "https://github.com/l1asis/birthdays.git"
+Issues = "https://github.com/l1asis/birthdays/issues"
+
+[project.scripts]
+birthdays = "birthdays.birthdays:main"
+bday = "birthdays.birthdays:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/birthdays"]
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.ruff.lint.isort]
+combine-as-imports = true

birthdays_cli-0.1.0/src/birthdays/__init__.py

@@ -0,0 +1,32 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("birthdays-cli")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+__about__ = rf"""
+    ✦         ̲     ✦      ✦         🔥          ✦
+        '    (o)       .     🔥     /^\    🔥        ✦
+             ╱:╲           __/^\____|_|____/^\__   *
+    +    ✦  ╱.:|╲    ✦    /  |_|           |_|  \
+           ╱..::|╲        \_____________________/     ✦
+          ╱...:::|╲    ✦  |  . . . . . . . . .  |
+     .   (_________)      | -~-~-~-~-~-~-~-~-~- | ✦
+        ╭╯       ╭─╯      | ~-~-~-~-~-~-~-~-~-~ |     *
+        ╰────────╯        *_____________________*
+
+  birthdays: Your birthday list is in your hands only.
+  ----------------------------------------------------------
+  Version:      {__version__}
+  Author:       Volodymyr Horshenin (@l1asis)
+  License:      MIT
+  Repository:   https://github.com/l1asis/birthdays
+
+  Description: 
+  A command-line utility for displaying and managing birthdays
+  from JSON- or vCard-based contacts.
+
+  Usage:
+  Run `python -m birthdays --help` to see available commands.
+"""

birthdays_cli-0.1.0/src/birthdays/__main__.py

@@ -0,0 +1,4 @@
+from .birthdays import main
+
+if __name__ == "__main__":
+    main()