tsukimoji 0.1.1__tar.gz

tsukimoji-0.1.1/LICENSE

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

tsukimoji-0.1.1/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: tsukimoji
+Version: 0.1.1
+Summary: Moon phase emoji for any date
+Author-email: Sam Lehman <grieve@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/samlehman/tsukimoji
+Keywords: moon,moon-phase,emoji,lunar,astronomy
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# tsukiMOJi
+
+Moon phase emoji for any date. 月 (tsuki, "moon") + moji, as in emoji.
+
+```python
+from tsukimoji import get_moon_phase, emoji
+
+phase = get_moon_phase()
+phase.emoji          # "🌔"
+phase.name           # "Waxing Gibbous"
+phase.age_days       # 12.3
+phase.illumination   # 0.87
+
+emoji()              # just the emoji, for "now"
+
+from datetime import datetime, timezone
+get_moon_phase(datetime(2026, 1, 1, tzinfo=timezone.utc))  # phase for any specific time
+```
+
+## Installation
+
+```
+pip install tsukimoji
+```
+
+## How it works
+
+tsukiMOJi measures elapsed time since a known new moon (2000-01-06
+18:14 UTC) against the synodic month (29.530588853 days) to find how far
+into the current lunar cycle a given moment falls, then maps that
+fraction onto the eight standard moon-phase emoji (🌑🌒🌓🌔🌕🌖🌗🌘).
+Illumination is derived separately from the same cycle position via a
+cosine curve, for display purposes.
+
+## License
+
+MIT
+
+---
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/samlehman/tsukimoji/main/made-in-baltimore.png" alt="Made in Baltimore" width="88" align="middle">
+  &nbsp;&nbsp;☕ <a href="https://paypal.me/samlehman">Buy me a coffee</a> · <a href="https://paypal.me/samlehman">こーひーをおごって</a>
+</p>

tsukimoji-0.1.1/README.md

@@ -0,0 +1,44 @@
+# tsukiMOJi
+
+Moon phase emoji for any date. 月 (tsuki, "moon") + moji, as in emoji.
+
+```python
+from tsukimoji import get_moon_phase, emoji
+
+phase = get_moon_phase()
+phase.emoji          # "🌔"
+phase.name           # "Waxing Gibbous"
+phase.age_days       # 12.3
+phase.illumination   # 0.87
+
+emoji()              # just the emoji, for "now"
+
+from datetime import datetime, timezone
+get_moon_phase(datetime(2026, 1, 1, tzinfo=timezone.utc))  # phase for any specific time
+```
+
+## Installation
+
+```
+pip install tsukimoji
+```
+
+## How it works
+
+tsukiMOJi measures elapsed time since a known new moon (2000-01-06
+18:14 UTC) against the synodic month (29.530588853 days) to find how far
+into the current lunar cycle a given moment falls, then maps that
+fraction onto the eight standard moon-phase emoji (🌑🌒🌓🌔🌕🌖🌗🌘).
+Illumination is derived separately from the same cycle position via a
+cosine curve, for display purposes.
+
+## License
+
+MIT
+
+---
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/samlehman/tsukimoji/main/made-in-baltimore.png" alt="Made in Baltimore" width="88" align="middle">
+  &nbsp;&nbsp;☕ <a href="https://paypal.me/samlehman">Buy me a coffee</a> · <a href="https://paypal.me/samlehman">こーひーをおごって</a>
+</p>

tsukimoji-0.1.1/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tsukimoji"
+version = "0.1.1"
+description = "Moon phase emoji for any date"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Sam Lehman", email = "grieve@gmail.com" }]
+keywords = ["moon", "moon-phase", "emoji", "lunar", "astronomy"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Developers",
+]
+
+[project.urls]
+Homepage = "https://github.com/samlehman/tsukimoji"
+
+[tool.setuptools.packages.find]
+where = ["src"]

tsukimoji-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tsukimoji-0.1.1/src/tsukimoji/__init__.py

@@ -0,0 +1,88 @@
+"""tsukiMOJi: moon phase emoji for any date.
+
+(tsuki, "moon") + moji, as in emoji.
+
+Ported from the original moon-phase.html JavaScript prototype.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+__all__ = [
+    "SYNODIC_MONTH_DAYS",
+    "KNOWN_NEW_MOON",
+    "PHASES",
+    "MoonPhase",
+    "get_moon_phase",
+    "emoji",
+    "name",
+]
+
+__version__ = "0.1.1"
+
+SYNODIC_MONTH_DAYS = 29.530588853
+_SYNODIC_MONTH_SECONDS = SYNODIC_MONTH_DAYS * 24 * 60 * 60
+
+# A known new moon reference point: 2000-01-06 18:14 UTC.
+KNOWN_NEW_MOON = datetime(2000, 1, 6, 18, 14, 0, tzinfo=timezone.utc)
+
+PHASES = (
+    ("\U0001F311", "New Moon"),
+    ("\U0001F312", "Waxing Crescent"),
+    ("\U0001F313", "First Quarter"),
+    ("\U0001F314", "Waxing Gibbous"),
+    ("\U0001F315", "Full Moon"),
+    ("\U0001F316", "Waning Gibbous"),
+    ("\U0001F317", "Last Quarter"),
+    ("\U0001F318", "Waning Crescent"),
+)
+
+
+@dataclass(frozen=True)
+class MoonPhase:
+    emoji: str
+    name: str
+    age_days: float
+    illumination: float
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.emoji
+
+
+def get_moon_phase(when: Optional[datetime] = None) -> MoonPhase:
+    """Return the MoonPhase for ``when`` (defaults to now, UTC).
+
+    A naive ``datetime`` is treated as UTC.
+    """
+    if when is None:
+        when = datetime.now(timezone.utc)
+    elif when.tzinfo is None:
+        when = when.replace(tzinfo=timezone.utc)
+
+    elapsed_seconds = (when - KNOWN_NEW_MOON) / timedelta(seconds=1)
+    cycles = elapsed_seconds / _SYNODIC_MONTH_SECONDS
+    age = ((cycles % 1) + 1) % 1
+    index = int((age + 1 / 16) * 8) % 8
+    illumination = (1 - math.cos(age * 2 * math.pi)) / 2
+
+    phase_emoji, phase_name = PHASES[index]
+    return MoonPhase(
+        emoji=phase_emoji,
+        name=phase_name,
+        age_days=age * SYNODIC_MONTH_DAYS,
+        illumination=illumination,
+    )
+
+
+def emoji(when: Optional[datetime] = None) -> str:
+    """Shortcut: just the emoji for ``when`` (defaults to now)."""
+    return get_moon_phase(when).emoji
+
+
+def name(when: Optional[datetime] = None) -> str:
+    """Shortcut: just the phase name for ``when`` (defaults to now)."""
+    return get_moon_phase(when).name

tsukimoji-0.1.1/src/tsukimoji.egg-info/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: tsukimoji
+Version: 0.1.1
+Summary: Moon phase emoji for any date
+Author-email: Sam Lehman <grieve@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/samlehman/tsukimoji
+Keywords: moon,moon-phase,emoji,lunar,astronomy
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# tsukiMOJi
+
+Moon phase emoji for any date. 月 (tsuki, "moon") + moji, as in emoji.
+
+```python
+from tsukimoji import get_moon_phase, emoji
+
+phase = get_moon_phase()
+phase.emoji          # "🌔"
+phase.name           # "Waxing Gibbous"
+phase.age_days       # 12.3
+phase.illumination   # 0.87
+
+emoji()              # just the emoji, for "now"
+
+from datetime import datetime, timezone
+get_moon_phase(datetime(2026, 1, 1, tzinfo=timezone.utc))  # phase for any specific time
+```
+
+## Installation
+
+```
+pip install tsukimoji
+```
+
+## How it works
+
+tsukiMOJi measures elapsed time since a known new moon (2000-01-06
+18:14 UTC) against the synodic month (29.530588853 days) to find how far
+into the current lunar cycle a given moment falls, then maps that
+fraction onto the eight standard moon-phase emoji (🌑🌒🌓🌔🌕🌖🌗🌘).
+Illumination is derived separately from the same cycle position via a
+cosine curve, for display purposes.
+
+## License
+
+MIT
+
+---
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/samlehman/tsukimoji/main/made-in-baltimore.png" alt="Made in Baltimore" width="88" align="middle">
+  &nbsp;&nbsp;☕ <a href="https://paypal.me/samlehman">Buy me a coffee</a> · <a href="https://paypal.me/samlehman">こーひーをおごって</a>
+</p>

tsukimoji-0.1.1/src/tsukimoji.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+src/tsukimoji/__init__.py
+src/tsukimoji.egg-info/PKG-INFO
+src/tsukimoji.egg-info/SOURCES.txt
+src/tsukimoji.egg-info/dependency_links.txt
+src/tsukimoji.egg-info/top_level.txt
+tests/test_tsukimoji.py

tsukimoji-0.1.1/src/tsukimoji.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tsukimoji-0.1.1/src/tsukimoji.egg-info/top_level.txt

@@ -0,0 +1 @@
+tsukimoji

tsukimoji-0.1.1/tests/test_tsukimoji.py

@@ -0,0 +1,80 @@
+import os
+import sys
+import unittest
+from datetime import datetime, timedelta, timezone
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from tsukimoji import (  # noqa: E402
+    KNOWN_NEW_MOON,
+    PHASES,
+    SYNODIC_MONTH_DAYS,
+    emoji,
+    get_moon_phase,
+    name,
+)
+
+
+class TestTsukimoji(unittest.TestCase):
+    def test_new_moon_instant(self):
+        phase = get_moon_phase(KNOWN_NEW_MOON)
+        self.assertEqual(phase.emoji, "\U0001F311")
+        self.assertEqual(phase.name, "New Moon")
+        self.assertLess(phase.illumination, 0.01)
+
+    def test_full_moon_half_cycle_later(self):
+        half_cycle_later = KNOWN_NEW_MOON + timedelta(days=SYNODIC_MONTH_DAYS / 2)
+        phase = get_moon_phase(half_cycle_later)
+        self.assertEqual(phase.emoji, "\U0001F315")
+        self.assertGreater(phase.illumination, 0.99)
+
+    def test_sample_is_known_phase(self):
+        sample = get_moon_phase(datetime(2026, 10, 1, 12, 0, tzinfo=timezone.utc))
+        known_emoji = {e for e, _ in PHASES}
+        self.assertIn(sample.emoji, known_emoji)
+        self.assertGreaterEqual(sample.age_days, 0)
+        self.assertLess(sample.age_days, 29.6)
+
+    def test_naive_datetime_treated_as_utc(self):
+        naive = datetime(2026, 10, 1, 12, 0)
+        aware = datetime(2026, 10, 1, 12, 0, tzinfo=timezone.utc)
+        self.assertEqual(get_moon_phase(naive), get_moon_phase(aware))
+
+    def test_shortcuts_match(self):
+        when = datetime(2026, 6, 15, tzinfo=timezone.utc)
+        phase = get_moon_phase(when)
+        self.assertEqual(emoji(when), phase.emoji)
+        self.assertEqual(name(when), phase.name)
+
+    def test_every_phase_at_its_exact_point(self):
+        # In this cycle, before 2000, and well after.
+        for cycle in (0, -3, 120):
+            for k, (expected_emoji, expected_name) in enumerate(PHASES):
+                with self.subTest(cycle=cycle, phase=expected_name):
+                    phase = get_moon_phase(_at_cycle(cycle + k / 8))
+                    self.assertEqual(phase.emoji, expected_emoji)
+                    self.assertEqual(phase.name, expected_name)
+
+    def test_phase_boundaries(self):
+        # Each phase changes halfway between exact points, at (2k + 1)/16.
+        # The last boundary (15/16) wraps back round to New Moon.
+        hour = timedelta(hours=1)
+        for k, (_, before) in enumerate(PHASES):
+            after = PHASES[(k + 1) % 8][1]
+            boundary = (2 * k + 1) / 16
+            with self.subTest(boundary=f"{2 * k + 1}/16"):
+                self.assertEqual(get_moon_phase(_at_cycle(boundary) - hour).name, before)
+                self.assertEqual(get_moon_phase(_at_cycle(boundary) + hour).name, after)
+
+    def test_quarters_half_lit(self):
+        self.assertAlmostEqual(get_moon_phase(_at_cycle(2 / 8)).illumination, 0.5, places=3)
+        self.assertAlmostEqual(get_moon_phase(_at_cycle(6 / 8)).illumination, 0.5, places=3)
+
+
+def _at_cycle(cycles):
+    """Moment at a given number of cycles (whole or fractional) from the reference."""
+    return KNOWN_NEW_MOON + timedelta(days=cycles * SYNODIC_MONTH_DAYS)
+
+
+if __name__ == "__main__":
+    unittest.main()