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.
- birdalbum-1.0.0/.gitignore +16 -0
- birdalbum-1.0.0/LICENSE +21 -0
- birdalbum-1.0.0/PKG-INFO +71 -0
- birdalbum-1.0.0/README.md +53 -0
- birdalbum-1.0.0/birdalbum/__init__.py +58 -0
- birdalbum-1.0.0/birdalbum/__main__.py +24 -0
- birdalbum-1.0.0/pyproject.toml +28 -0
- birdalbum-1.0.0/tests/test_birdalbum.py +63 -0
birdalbum-1.0.0/LICENSE
ADDED
|
@@ -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.
|
birdalbum-1.0.0/PKG-INFO
ADDED
|
@@ -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()
|