Reference guides, examples, and API documentation for cozy-kit.
pip install cozy-kit
from cozy_kit import Greeting, CozyUI greet = Greeting(name="Youssef", nickname="yo") ui = CozyUI() print(ui.cozy_title("hello, world")) # ═══════ hello, world ═══════ print(greet.auto_greet()) # Good Morning Youssef! # Or good morning Yo! # Rise & Shine # Every morning is a fresh start...
Six independent classes. Friendly APIs. Thoughtful defaults. Zero ceremony.
cozy-kit is on PyPI and installs with a single command. Python 3.8+ is required.
plyer — desktop notifications (auto-installed)requests — PyPI update checks (auto-installed)
Clone the repo and install in editable mode from within the project/ directory.
# Install from PyPI pip install cozy-kit # Upgrade to latest pip install --upgrade cozy-kit # Editable / contributor install git clone https://github.com/youssefahmed2017/cozy-kit cd cozy-kit pip install -e .
pip install to running in seconds.Import what you need, instantiate the class, call the method. No setup, no config files, no global state. Just small, friendly classes.
Every class is independent — use one, some, or all in the same script. Each manages its own state.
from cozy_kit import Greeting, Timer, TextEditor, CozyUI # Personalised greetings greet = Greeting(name="Youssef", nickname="yo") print(greet.welcome()) # Welcome Youssef! print(greet.auto_greet()) # Picks based on time + season # A Pomodoro that just works timer = Timer() timer.start_pomodoro(work_time=25, break_time=5, long_break_time=15, show=print) # Text tricks fx = TextEditor() print(fx.to_morse("hi")) # .... .. print(fx.corrupt("vibes", mode="bubble")) # ⓥⓘⓑⓔⓢ # Terminal UI helpers ui = CozyUI() print(ui.cozy_box("done!")) # ╔═══════╗ # ║ done! ║ # ╚═══════╝
Each class manages its own state and works standalone. There's no shared global state between Greeting, Timer, TextEditor, or any other class.
show CallbackTimer methods that display live output take a show callable. Pass print, a logger, a UI label updater — any function that accepts a string.
timer.countdown(5, "min", show=print)Greeting loads quotes and stories from bundled JSON files. Permanently extend them with add_bedtime_story(), add_motivation(), and add_fun_fact().
auto_greet() uses the system clock and month to pick between morning, afternoon, evening, and night — with time bands that shift between winter, summer, spring, and autumn.
Most methods return plain strings rather than printing directly. You can print(), log, assign to variables, or splice outputs together freely.
A small class that knows your name, the time of day, the season, and whether today is a holiday. Loads quotes and stories from bundled JSON databases, and lets you add your own.
from cozy_kit import Greeting
Keyword arguments: name, age, gender, nickname. All optional. name defaults to "User". Names are auto-titlecased.
Returns a personalized welcome message.
A goodbye message, optionally addressed to a destination. Defaults to a generic farewell if omitted.
A morning greeting paired with a random quote from the mornings database.
An afternoon greeting with a random afternoon quote.
An evening greeting with a random evening quote.
Goodnight wishes plus one randomly chosen bundled bedtime story.
Selects a greeting based on the current hour and season. Checks holiday_greet() first — if today is a holiday, returns that instead. Time bands shift between winter, summer, and other seasons.
Returns a random motivational quote (title + body joined).
Returns a random fun fact from the bundled database.
Returns a random pick from any of the four time-of-day greeters.
Returns a wish if today is a recognized holiday, or None otherwise. Supported: New Year's Day (Jan 1), Valentine's Day (Feb 14), Earth Day (Apr 22), International Friendship Day (Jul 30), World Smile Day (Oct 4), Children's Day (Nov 20).
Permanently appends a new bedtime story to bedtime_stories.json. Both must be non-empty — raises InvalidStoryError otherwise.
Appends a new motivational quote to motivations.json.
Appends a new fun fact to fun_facts.json.
from cozy_kit import Greeting g = Greeting(name="Youssef", nickname="yo", age=8) # Time-aware automatic greeting print(g.auto_greet()) # Good Morning Youssef! # Or good morning Yo! # Anyways, here's a quick morning quote. # # Rise & Shine # Every morning is a fresh start... # Holidays light up automatically print(g.holiday_greet()) # 🎉 Happy New Year's Day, Youssef! # A new year means new chances to grow. # A ready-to-print motivational quote print(g.motivate()) # One Step # You don't have to see the whole staircase... # Add your own bedtime story g.add_bedtime_story( title="The Sleepy Robot", content="Once upon a circuit board...", ) # Goodbye with a destination print(g.bye(destination="the gym")) # Bye Youssef! Have a nice day at the gym! # Or bye Yo!
Countdowns, Pomodoro cycles, stopwatches, and waits — all with a single
consistent API. Every blocking timer accepts a show callback so
you can route output anywhere: stdout, a curses pane, a Tkinter label.
from cozy_kit import Timer
No arguments. Initializes internal state for Pomodoro control and stopwatch tracking.
time_type is "sec", "min", or "hour". Calls show each second with the remaining time as MM:SS or HH:MM:SS. Fires a desktop notification at zero.
Creates a new Thread, then runs a full cycle: work → short break → work → … → long break every 4 work sessions. All times are in minutes. Sends a desktop notification at each transition.
Pauses a running Pomodoro. Raises PomodoroNotStartedError if not started.
Resumes a paused Pomodoro. Raises PomodoroNotPausedError if not paused.
Stops the Pomodoro and resets state. Raises PomodoroNotStartedError if not started.
A friendlier time.sleep(). Accepts "sec", "min", or "hour".
Returns the current local time as HH:MM:SS.
Starts the stopwatch and records the start timestamp.
Stops the stopwatch and returns elapsed time as HH:MM:SS. Resets state so the instance is reusable. Raises StopWatchNotStartedError if never started.
from cozy_kit import Timer t = Timer() # 5-minute countdown t.countdown(count=5, time_type="min", show=print) # 04:59 04:58 ... 00:00 ⏰ Time's up! # Full Pomodoro session t.start_pomodoro( work_time=25, break_time=5, long_break_time=15, show=print, ) # 💻 Work Time → ☕ Short Break → 💻 Work Time → ... # Stopwatch t.start_stopwatch() # ... do some work ... print(t.end_stopwatch()) # 00:03:12 # Current time + friendly wait print(t.get_time()) # 14:32:08 t.wait(count=2, time_type="sec")
Encodings, case transforms, analysis tools, and four playful corruption modes.
Every method expects a non-empty string and raises EmptyTextError on
empty input.
from cozy_kit import TextEditor
No arguments.
Converts text to Morse code. Letters, digits, and common punctuation are supported. Unknown characters become ?.
Caesar cipher with full wrap-around. Negative shifts decode. shift must be an integer — raises InvalidShiftError otherwise. Non-alpha characters pass through unchanged.
Standard case conversions.
Convert space-separated text to snake_case, kebab-case, or PascalCase.
Word count (whitespace-delimited), total character count, and vowel count (a e i o u, case-insensitive).
Reverses the string character by character.
Strip all spaces, or all punctuation characters.
Replaces every occurrence of replacement with a space.
Inserts a space after each character: "hi" → "h i".
Reskins text in one of four moods (input is lowercased first):
"glitch" — Unicode combining diacritics"broken" — ASCII-art replacements"bubble" — Circled Unicode letters (ⓐⓑⓒ…)"void" — Occult symbol substitutionsfrom cozy_kit import TextEditor fx = TextEditor() # Encoding print(fx.to_morse("hello world")) # .... . .-.. .-.. --- / .-- --- .-. .-.. -.. print(fx.caesar_cipher("hello", shift=3)) # khoor print(fx.caesar_cipher("khoor", shift=-3)) # hello # Case & format print(fx.snake_case("Cozy Kit Demo")) # cozy_kit_demo print(fx.kebab_case("Cozy Kit Demo")) # cozy-kit-demo print(fx.pascal_case("cozy kit demo")) # CozyKitDemo # Analysis print(fx.word_count("hi there friend")) # 3 print(fx.count_vowels("cozy kit")) # 2 print(fx.char_count("hello")) # 5 print(fx.reverse("warmth")) # htmraw # Cleanup print(fx.remove_spaces("cozy kit")) # cozykit print(fx.remove_punctuation("hey, yo!")) # hey yo print(fx.space_out_letters("hi")) # h i # Corruption modes print(fx.corrupt("vibes", mode="bubble")) # ⓥⓘⓑⓔⓢ print(fx.corrupt("hi", mode="broken")) # #! print(fx.corrupt("void", mode="void")) # V̴⊘ɨ◊ print(fx.corrupt("hi", mode="glitch")) # ̴h̶̵i̷
Adds ANSI escape codes for color, background, and text styling to any string.
Style names are case-insensitive and spaces are normalized to underscores, so
"Bold Italic" and "bold_italic" are equivalent.
from cozy_kit import TextCustomizations
No arguments. Initializes the ANSI style mapping internally.
Wraps text with one or more ANSI styles then appends a reset. Unknown style names raise InvalidStyleError. Styles stack — pass as many as you like.
ANSI codes require a supporting terminal. Windows Terminal, PowerShell 7+, macOS Terminal, and most Linux terminals work natively. Legacy cmd.exe may not.
from cozy_kit import TextCustomizations c = TextCustomizations() # Single style print(c.customize("warning!", "red")) # → "warning!" in red # Stack multiple styles print(c.customize("important", "bold", "yellow")) # → bold yellow text print(c.customize("alert", "white", "red_bg", "bold")) # → bold white text on red background # Pre-mixed combos print(c.customize("emphatic", "bold_italic_underline")) # Case-insensitive — spaces become underscores print(c.customize("hey", "Bold Italic")) # → bold italic "hey" # Bright variants print(c.customize("shiny", "green_bright", "bold")) # → bold bright-green text
Pretty box-drawing for terminals. Every helper returns a plain string so you
can print(), log, or splice them anywhere. Column widths auto-size
to content.
from cozy_kit import CozyUI
No arguments.
A horizontal rule of any character, any length.
Wraps text with equal dividers on each side: ═══ text ═══. length is split evenly left and right.
A full box-drawn table with auto-computed column widths. headers is a list of strings; rows is a list of equal-length lists. All cells are auto-padded.
A rounded bar — blue blocks for completed deciles, red blocks for the rest. Example: ━━━━━━━ (blue) ━━━ (red) 70%.
A single-line message wrapped in a tidy double-line Unicode box.
A live terminal spinner that animates for the given duration, then prints Done!. load_type: "sec", "min", or "hour". style: "line", "dots", or "arrows". message: Anything you want to display like Loading.
from cozy_kit import CozyUI ui = CozyUI() print(ui.cozy_title("Daily Stats")) # ═══════ Daily Stats ═══════ print(ui.cozy_table( headers=["Task", "Status", "Time"], rows=[ ["Code review", "done", "22m"], ["Write docs", "in prog", "1h"], ["Refactor", "queued", "—"], ], )) # ╔═════════════╦═════════╦══════╗ # ║ Task ║ Status ║ Time ║ # ╠═════════════╬═════════╬══════╣ # ║ Code review ║ done ║ 22m ║ # ║ Write docs ║ in prog ║ 1h ║ # ║ Refactor ║ queued ║ — ║ # ╚═════════════╩═════════╩══════╝ print(ui.progress_bar(70)) # ━━━━━━━ (blue) ━━━ (red) 70% print(ui.cozy_box("all done!")) # ╔═══════════╗ # ║ all done! ║ # ╚═══════════╝ print(ui.divider(symbol="─", length=20)) # ──────────────────── # Live spinner — animates for 3 sec, then prints Done! ui.spinner(loadtime=3, load_type="sec", style="dots") # . .. ... .... → Done!
A tiny class that hands you back package metadata as a ready-to-print table.
It's what powers cozy-kit --info on the command line.
from cozy_kit import Details
No arguments. Pre-loads author, email, description, GitHub, PyPI, docs, and license info.
Returns a fully-formatted CozyUI table with all metadata fields.
from cozy_kit import Details d = Details() print(d.about()) # ╔══════════════╦══════════════════════════════════╗ # ║ Detail ║ Value ║ # ╠══════════════╬══════════════════════════════════╣ # ║ Author ║ Youssef Ahmed ║ # ║ Author email ║ youssef.ahmed.29062017@gmail.com ║ # ║ Description ║ A cozy Python package… ║ # ║ GitHub ║ github.com/youssefahmed2017/… ║ # ║ PyPI ║ pypi.org/project/cozy-kit/ ║ # ║ Our Docs ║ cozy-docs.vercel.app ║ # ║ license ║ MIT ║ # ╚══════════════╩══════════════════════════════════╝
Installing the package also registers a cozy-kit command on your PATH.
Two flags for checking what you've got installed — and each run quietly checks PyPI
for newer versions.
Prints the installed version, e.g. cozy-kit v1.0.3.
Prints the full Details.about() metadata table — author, email, description, links, license, and a quick explanation paragraph.
Print the License for cozy-kit, e.g. MIT License
Opens cozy-kit's PyPI page in a new tab.
Opens cozy-kit's GitHub repo in a new tab.
Opens cozy-kit's Homepage in a new tab.
Opens cozy-kit's Documentation website in a new tab.
# Check the installed version cozy-kit --version # CozyKit v1.0.3 # Show package details cozy-kit --info # ╔══════════════╦══════════════════════════════════╗ # ║ Detail ║ Value ║ # ╠══════════════╬══════════════════════════════════╣ # ║ Author ║ Youssef Ahmed ║ # ║ Author email ║ youssef.ahmed.29062017@gmail.com ║ # ║ ... ║ ... ║ # ╚══════════════╩══════════════════════════════════╝ # This package is a package made by Youssef Ahmed. # The package's latest version was v1.0.3. # The package has started to reach a great point where it is starting to become stable # Show License cozy-kit --license # MIT License # Open some Project URLs cozy-kit --pypi # Opens "https://pypi.org/project/cozy-kit" # Successfully opened cozy-kit's PyPI page ✔️ cozy-kit --github # Opens "https://github.com/youssefahmed2017/cozy-kit" # Successfully opened cozy-kit's GitHub repo ✔️ cozy-kit --homepage # Opens "https://cozykit-home.vercel.app" # Successfully opened cozy-kit's Homepage ✔️ cozy-kit --docs # Opens "https://cozy-docs.vercel.app" # Successfully opened cozy-kit's Documentation ✔️
cozy-kit exposes a single settings object — a pre-instantiated
Settings instance — that controls package-level behavior.
Import and mutate it before using other classes.
When True (the default), the CLI checks PyPI on every invocation
and prints a notice if a newer version is available.
Set to False to silence these notices.
Changes persist for the lifetime of your Python process. Set it once at the top of your script before other imports.
from cozy_kit import settings # Default: update checks are ON print(settings.notice_if_on_older_update) # True # Disable update notifications settings.notice_if_on_older_update = False # Now import and use classes normally from cozy_kit import Greeting g = Greeting(name="Youssef") print(g.welcome()) # Welcome Youssef! # (no PyPI update notice printed)
Three complete, copy-paste-ready scripts showing common patterns.
from cozy_kit import Greeting, CozyUI ui = CozyUI() greet = Greeting(name="Youssef", nickname="yo") print(ui.cozy_title("Daily Greeter")) print(greet.auto_greet()) print(ui.divider()) print(greet.motivate())
import time from cozy_kit import Timer, CozyUI t = Timer() ui = CozyUI() t.pomodoro(work_time=25, break_time=5, long_break_time=15, show=print) time.sleep(10) print(ui.cozy_box("Pausing...")) t.pause_pomodoro() time.sleep(3) print(ui.cozy_box("Resuming!")) t.resume_pomodoro() # t.stop_pomodoro() — call when done
from cozy_kit import CozyUI, TextCustomizations, TextEditor ui = CozyUI() c = TextCustomizations() fx = TextEditor() header = c.customize("RESULTS", "bold", "cyan") print(ui.cozy_title(header)) # Bold Cyan "====== RESULTS ======" print(ui.cozy_table( headers=["Task", "Status", "Notes"], rows=[ ["Write tests", "✓ done", "45m"], ["Deploy", "⚠ pending", "—"], ["Docs", "✓ done", "1h"], ], )) # ╔═════════════╦═══════════╦═══════╗ # ║ Task ║ Status ║ Notes ║ # ╠═════════════╬═══════════╬═══════╣ # ║ Write tests ║ ✓ done ║ 45m ║ # ║ Deploy ║ ⚠ pending ║ — ║ # ║ Docs ║ ✓ done ║ 1h ║ # ╚═════════════╩═══════════╩═══════╝ print(ui.progress_bar(66)) # ━━━━━━━ (blue) ━━━ (red) 66% label = fx.snake_case("My Feature Flag") print(c.customize(label, "dim", "yellow")) # dim yellow "my_feature_flag"
plyer (used in Timer.start_pomodoro()) may require extra setup on some Linux environments (e.g., libnotify).cmd.exe does not — switch to Windows Terminal to fix this immediately.Import settings and set notice_if_on_older_update = False at the top of your script before other cozy-kit imports.
from cozy_kit import settings settings.notice_if_on_older_update = False
add_bedtime_story(title, content), add_motivation(name, content), or add_fun_fact(name, content). Each permanently appends to the bundled JSON files, so additions persist across scripts.