birdalbum 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,16 @@
1
+ .env
2
+ .env.*
3
+ !.env.example
4
+ .venv/
5
+ .build/
6
+ build/
7
+ DerivedData/
8
+ models/
9
+ verification/dataset/
10
+ pipeline/batch/
11
+ *.xcuserstate
12
+ xcuserdata/
13
+ .DS_Store
14
+ __pycache__/
15
+ .dev.vars
16
+ node_modules/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Bird Album (https://birdalbum.com)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,71 @@
1
+ Metadata-Version: 2.5
2
+ Name: birdalbum
3
+ Version: 1.0.0
4
+ Summary: Bird of the day from Bird Album (birdalbum.com), plus links to 11,000+ AI-generated bird stickers (CC BY 4.0) and species pages. Standard library only.
5
+ Project-URL: Homepage, https://birdalbum.com/developers/
6
+ Project-URL: Source, https://github.com/alchaincyf/huashu-bird-sticker
7
+ Project-URL: Issues, https://github.com/alchaincyf/huashu-bird-sticker/issues
8
+ Author: Bird Album
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: bird of the day,birding,birds,illustrations,ornithology,stickers
12
+ Classifier: Development Status :: 5 - Production/Stable
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Requires-Python: >=3.9
17
+ Description-Content-Type: text/markdown
18
+
19
+ # birdalbum
20
+
21
+ A tiny client for [Bird Album](https://birdalbum.com/), a free bird guide with illustrations of 11,000+ species in 15 languages.
22
+
23
+ - `bird_of_the_day()` – today's bird: one species per UTC day, the same for everyone
24
+ - `sticker()` – the URL of a species' illustration in the open sticker repository
25
+ - `species_url()` – the link to a species page on birdalbum.com
26
+
27
+ Standard library only (`urllib`), Python 3.9+.
28
+
29
+ ```sh
30
+ pip install birdalbum
31
+ ```
32
+
33
+ ```python
34
+ from birdalbum import bird_of_the_day, sticker, species_url
35
+
36
+ bird = bird_of_the_day("ja")
37
+ bird["name"] # name in Japanese (English if there is none)
38
+ bird["sci"] # scientific name
39
+ bird["url"] # species page on birdalbum.com
40
+ bird["image"] # illustration (WebP)
41
+ bird["credit"] # credit line in the same language
42
+
43
+ sticker("Alcedo atthis")
44
+ # 'https://cdn.jsdelivr.net/gh/alchaincyf/huashu-bird-sticker@main/stickers/Coraciiformes/Alcedinidae/Alcedo_atthis.webp'
45
+
46
+ species_url("common-kingfisher", "zh-Hans")
47
+ # 'https://birdalbum.com/zh/birds/common-kingfisher/'
48
+ ```
49
+
50
+ Languages: `en`, `zh-Hans`, `zh-Hant`, `ja`, `ko`, `de`, `fr`, `es`, `pt-BR`, `it`, `nl`, `ru`, `sv`, `da`, `pl`. Locale strings such as `ja_JP` or `zh_TW` are mapped to the closest one; anything else falls back to English.
51
+
52
+ ## Command line
53
+
54
+ ```sh
55
+ python -m birdalbum # uses your system language
56
+ python -m birdalbum de
57
+ ```
58
+
59
+ ## Notes
60
+
61
+ - `bird_of_the_day()` calls `https://birdalbum.com/today.json`. The response also has `names` (all languages), `card` (an SVG card for READMEs) and `license`.
62
+ - `sticker()` downloads the sticker index (about 2.6 MB) from jsDelivr on first use and returns `None` for names it does not know. The sticker repository follows the AviList 2026 checklist while the website follows IOC 15.2, so a few species names differ; for today's bird, use `bird["image"]`.
63
+ - Network errors are raised as `urllib.error.URLError` (a subclass of `OSError`).
64
+
65
+ ## Credit and license
66
+
67
+ The illustrations are AI-generated and may contain errors. They are licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Please credit: **Illustration: Bird Album (birdalbum.com)**.
68
+
69
+ This package's code is MIT licensed.
70
+
71
+ Questions and corrections: [GitHub issues](https://github.com/alchaincyf/huashu-bird-sticker/issues) · [birdalbum.com/developers](https://birdalbum.com/developers/)
@@ -0,0 +1,53 @@
1
+ # birdalbum
2
+
3
+ A tiny client for [Bird Album](https://birdalbum.com/), a free bird guide with illustrations of 11,000+ species in 15 languages.
4
+
5
+ - `bird_of_the_day()` – today's bird: one species per UTC day, the same for everyone
6
+ - `sticker()` – the URL of a species' illustration in the open sticker repository
7
+ - `species_url()` – the link to a species page on birdalbum.com
8
+
9
+ Standard library only (`urllib`), Python 3.9+.
10
+
11
+ ```sh
12
+ pip install birdalbum
13
+ ```
14
+
15
+ ```python
16
+ from birdalbum import bird_of_the_day, sticker, species_url
17
+
18
+ bird = bird_of_the_day("ja")
19
+ bird["name"] # name in Japanese (English if there is none)
20
+ bird["sci"] # scientific name
21
+ bird["url"] # species page on birdalbum.com
22
+ bird["image"] # illustration (WebP)
23
+ bird["credit"] # credit line in the same language
24
+
25
+ sticker("Alcedo atthis")
26
+ # 'https://cdn.jsdelivr.net/gh/alchaincyf/huashu-bird-sticker@main/stickers/Coraciiformes/Alcedinidae/Alcedo_atthis.webp'
27
+
28
+ species_url("common-kingfisher", "zh-Hans")
29
+ # 'https://birdalbum.com/zh/birds/common-kingfisher/'
30
+ ```
31
+
32
+ Languages: `en`, `zh-Hans`, `zh-Hant`, `ja`, `ko`, `de`, `fr`, `es`, `pt-BR`, `it`, `nl`, `ru`, `sv`, `da`, `pl`. Locale strings such as `ja_JP` or `zh_TW` are mapped to the closest one; anything else falls back to English.
33
+
34
+ ## Command line
35
+
36
+ ```sh
37
+ python -m birdalbum # uses your system language
38
+ python -m birdalbum de
39
+ ```
40
+
41
+ ## Notes
42
+
43
+ - `bird_of_the_day()` calls `https://birdalbum.com/today.json`. The response also has `names` (all languages), `card` (an SVG card for READMEs) and `license`.
44
+ - `sticker()` downloads the sticker index (about 2.6 MB) from jsDelivr on first use and returns `None` for names it does not know. The sticker repository follows the AviList 2026 checklist while the website follows IOC 15.2, so a few species names differ; for today's bird, use `bird["image"]`.
45
+ - Network errors are raised as `urllib.error.URLError` (a subclass of `OSError`).
46
+
47
+ ## Credit and license
48
+
49
+ The illustrations are AI-generated and may contain errors. They are licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Please credit: **Illustration: Bird Album (birdalbum.com)**.
50
+
51
+ This package's code is MIT licensed.
52
+
53
+ Questions and corrections: [GitHub issues](https://github.com/alchaincyf/huashu-bird-sticker/issues) · [birdalbum.com/developers](https://birdalbum.com/developers/)
@@ -0,0 +1,58 @@
1
+ """Bird Album client: today's bird, sticker URLs and species page links. Standard library only."""
2
+ import json
3
+ import urllib.parse
4
+ import urllib.request
5
+
6
+ __version__ = "1.0.0"
7
+ __all__ = ["bird_of_the_day", "sticker", "species_url", "normalize_lang", "LANGS", "CREDIT"]
8
+
9
+ SITE = "https://birdalbum.com"
10
+ STICKER_INDEX = "https://cdn.jsdelivr.net/gh/alchaincyf/huashu-bird-sticker@main/data/stickers.json"
11
+ CREDIT = "Illustration: Bird Album (birdalbum.com)"
12
+ # Language code -> URL prefix on birdalbum.com
13
+ PREFIX = {"en": "", "zh-Hans": "zh", "zh-Hant": "zh-hant", "ja": "ja", "ko": "ko", "de": "de", "fr": "fr", "es": "es",
14
+ "pt-BR": "pt-br", "it": "it", "nl": "nl", "ru": "ru", "sv": "sv", "da": "da", "pl": "pl"}
15
+ LANGS = list(PREFIX)
16
+ # Cloudflare rejects urllib's default User-Agent
17
+ _HEADERS = {"User-Agent": f"birdalbum-python/{__version__}", "Accept": "application/json"}
18
+ _index = None
19
+
20
+
21
+ def normalize_lang(lang=None):
22
+ """Map "zh", "zh-TW", "ja_JP", "pt-br"... to one of LANGS; anything unknown becomes "en"."""
23
+ s = str(lang or "").lower().replace("_", "-")
24
+ for k in LANGS:
25
+ if s in (k.lower(), PREFIX[k]):
26
+ return k
27
+ if s.startswith("zh"):
28
+ return "zh-Hant" if any(t in s for t in ("hant", "tw", "hk", "mo")) else "zh-Hans"
29
+ base = s.split("-")[0]
30
+ return "pt-BR" if base == "pt" else base if base in LANGS else "en"
31
+
32
+
33
+ def _get_json(url, timeout=30):
34
+ with urllib.request.urlopen(urllib.request.Request(url, headers=_HEADERS), timeout=timeout) as r:
35
+ return json.load(r)
36
+
37
+
38
+ def bird_of_the_day(lang="en"):
39
+ """Today's bird as a dict (one species per UTC day, the same for everyone)."""
40
+ return _get_json(f"{SITE}/today.json?lang={urllib.parse.quote(normalize_lang(lang))}")
41
+
42
+
43
+ def sticker(scientific_name):
44
+ """jsDelivr URL of the sticker (WebP) for a scientific name, or None if the sticker repo has no such species.
45
+
46
+ The first call downloads the sticker index (about 2.6 MB); later calls reuse it.
47
+ """
48
+ global _index
49
+ if _index is None:
50
+ d = _get_json(STICKER_INDEX, timeout=60)
51
+ _index = {s["scientificName"].lower(): d["cdn"] + s["file"] for s in d["stickers"]}
52
+ return _index.get(" ".join(str(scientific_name).replace("_", " ").split()).lower())
53
+
54
+
55
+ def species_url(slug, lang="en"):
56
+ """Species page on birdalbum.com, e.g. species_url("common-kingfisher", "ja")."""
57
+ p = PREFIX[normalize_lang(lang)]
58
+ return f"{SITE}{'/' + p if p else ''}/birds/{urllib.parse.quote(slug)}/"
@@ -0,0 +1,24 @@
1
+ """Usage: python -m birdalbum [lang] e.g. python -m birdalbum ja"""
2
+ import locale
3
+ import sys
4
+
5
+ from . import LANGS, bird_of_the_day
6
+
7
+
8
+ def main(argv=None):
9
+ argv = sys.argv[1:] if argv is None else argv
10
+ if argv and argv[0] in ("-h", "--help"):
11
+ print("Usage: python -m birdalbum [lang]\nPrints today's bird from birdalbum.com. lang: " + ", ".join(LANGS))
12
+ return 0
13
+ lang = argv[0] if argv else (locale.getlocale()[0] or "en")
14
+ try:
15
+ b = bird_of_the_day(lang)
16
+ except OSError as e:
17
+ print(f"Could not reach birdalbum.com: {e}", file=sys.stderr)
18
+ return 1
19
+ print(f"{b['name']} ({b['sci']})\n{b['url']}\n{b['image']}\n{b['credit']}")
20
+ return 0
21
+
22
+
23
+ if __name__ == "__main__":
24
+ sys.exit(main())
@@ -0,0 +1,28 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.27"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "birdalbum"
7
+ version = "1.0.0"
8
+ description = "Bird of the day from Bird Album (birdalbum.com), plus links to 11,000+ AI-generated bird stickers (CC BY 4.0) and species pages. Standard library only."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ authors = [{ name = "Bird Album" }]
13
+ requires-python = ">=3.9"
14
+ keywords = ["birds", "bird of the day", "birding", "ornithology", "stickers", "illustrations"]
15
+ classifiers = [
16
+ "Development Status :: 5 - Production/Stable",
17
+ "Intended Audience :: Developers",
18
+ "Operating System :: OS Independent",
19
+ "Programming Language :: Python :: 3",
20
+ ]
21
+
22
+ [project.urls]
23
+ Homepage = "https://birdalbum.com/developers/"
24
+ Source = "https://github.com/alchaincyf/huashu-bird-sticker"
25
+ Issues = "https://github.com/alchaincyf/huashu-bird-sticker/issues"
26
+
27
+ [tool.hatch.build.targets.sdist]
28
+ include = ["birdalbum", "tests", "README.md", "LICENSE"]
@@ -0,0 +1,63 @@
1
+ import io
2
+ import json
3
+ import os
4
+ import unittest
5
+ from unittest import mock
6
+
7
+ import birdalbum
8
+
9
+
10
+ def fake_urlopen(responses, calls):
11
+ def urlopen(req, timeout=None):
12
+ calls.append(req)
13
+ url = req.full_url
14
+ return io.BytesIO(json.dumps(next(v for k, v in responses.items() if k in url)).encode())
15
+ return urlopen
16
+
17
+
18
+ class Offline(unittest.TestCase):
19
+ def setUp(self):
20
+ birdalbum._index = None
21
+
22
+ def test_species_url(self):
23
+ self.assertEqual(birdalbum.species_url("common-kingfisher"), "https://birdalbum.com/birds/common-kingfisher/")
24
+ self.assertEqual(birdalbum.species_url("common-kingfisher", "zh-Hans"), "https://birdalbum.com/zh/birds/common-kingfisher/")
25
+ self.assertEqual(birdalbum.species_url("common-kingfisher", "pt-BR"), "https://birdalbum.com/pt-br/birds/common-kingfisher/")
26
+ self.assertEqual(birdalbum.species_url("common-kingfisher", "xx"), "https://birdalbum.com/birds/common-kingfisher/")
27
+
28
+ def test_normalize_lang(self):
29
+ cases = {"ja_JP": "ja", "zh-TW": "zh-Hant", "zh_CN": "zh-Hans", "zh": "zh-Hans", "pt_PT": "pt-BR", "nb_NO": "en", None: "en"}
30
+ for given, want in cases.items():
31
+ self.assertEqual(birdalbum.normalize_lang(given), want, given)
32
+
33
+ def test_bird_of_the_day_and_sticker(self):
34
+ calls = []
35
+ responses = {
36
+ "today.json": {"name": "カワセミ", "sci": "Alcedo atthis"},
37
+ "stickers.json": {"cdn": "https://cdn.example/", "stickers": [
38
+ {"scientificName": "Alcedo atthis", "file": "stickers/a/Alcedo_atthis.webp"}]},
39
+ }
40
+ with mock.patch("urllib.request.urlopen", fake_urlopen(responses, calls)):
41
+ self.assertEqual(birdalbum.bird_of_the_day("ja-JP")["name"], "カワセミ")
42
+ self.assertEqual(calls[0].full_url, "https://birdalbum.com/today.json?lang=ja")
43
+ self.assertTrue(calls[0].get_header("User-agent").startswith("birdalbum-python/"))
44
+ self.assertEqual(birdalbum.sticker("Alcedo_atthis"), "https://cdn.example/stickers/a/Alcedo_atthis.webp")
45
+ self.assertEqual(birdalbum.sticker("alcedo ATTHIS"), "https://cdn.example/stickers/a/Alcedo_atthis.webp")
46
+ self.assertIsNone(birdalbum.sticker("Nonexistent bird"))
47
+ self.assertEqual(sum("stickers.json" in c.full_url for c in calls), 1)
48
+
49
+
50
+ @unittest.skipUnless(os.environ.get("NETWORK"), "set NETWORK=1 to run")
51
+ class Live(unittest.TestCase):
52
+ def test_live(self):
53
+ birdalbum._index = None
54
+ b = birdalbum.bird_of_the_day("zh-Hans")
55
+ self.assertRegex(b["date"], r"^\d{4}-\d{2}-\d{2}$")
56
+ self.assertIs(b["aiGenerated"], True)
57
+ self.assertTrue(b["url"].startswith("https://birdalbum.com/zh/birds/"))
58
+ self.assertRegex(birdalbum.sticker("Alcedo atthis"),
59
+ r"^https://cdn\.jsdelivr\.net/gh/alchaincyf/huashu-bird-sticker@main/stickers/.+/Alcedo_atthis\.webp$")
60
+
61
+
62
+ if __name__ == "__main__":
63
+ unittest.main()