Skip to content

Commit 20c0701

Browse files
dakrauthdakrauth
committed
Improved docs
1 parent 007fd20 commit 20c0701

File tree

12 files changed

+488
-142
lines changed

12 files changed

+488
-142
lines changed

‎Justfile

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ update:
2626
{{PIP}} install -U \
2727
build \
2828
pytest \
29+
docutils \
2930
pytest-sugar \
3031
pytest-clarity \
3132
freezegun \
@@ -132,3 +133,8 @@ strftime:
132133
f"Format Specifiers:\n{pt.get_string()}\n\n"
133134
"Notes:\n* - Locale-dependent\n+ - C99 extension\n! - when extension"
134135
)
136+
137+
# Preview README.rst
138+
docs:
139+
rst2html5 --output README.html README.rst
140+
open README.html

‎README.rst

Lines changed: 342 additions & 57 deletions
Large diffs are not rendered by default.

‎src/when/__init__.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
Calculate and convert times across time zones and cities of significant population.
33
"""
44

5-
__version__ = "3.2.1"
5+
__version__ = "3.3"
66
VERSION = tuple(int(i) for i in __version__.split("."))
77

88

‎src/when/cli.py

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,13 @@
11
#!/usr/bin/env python
22
import argparse
3-
import logging
43
import sys
4+
import logging
55
from pathlib import Path
66

77
from . import __version__, core, db, utils, lunar, exceptions
88
from . import timezones
99
from .config import Settings, __doc__ as FORMAT_HELP
1010

11-
logger = logging.getLogger(__name__)
12-
1311

1412
def get_parser(settings):
1513
class DBSizeAction(argparse.Action):
@@ -227,11 +225,14 @@ def log_config(verbosity, settings):
227225
logging.getLogger("asyncio").setLevel(logging.WARNING)
228226

229227
logging.basicConfig(level=log_level, format=log_format, force=True)
228+
logger = utils.logger()
230229
logger.debug(
231230
"Configuration files read: %s",
232231
", ".join(str(s) for s in settings.read_from) if settings.read_from else "None",
233232
)
234233

234+
return logger
235+
235236

236237
def main(sys_args, when=None, settings=None):
237238
if "--pdb" in sys_args: # pragma: no cover
@@ -258,7 +259,7 @@ def main(sys_args, when=None, settings=None):
258259
parser = get_parser(settings)
259260
args = parser.parse_args(sys_args)
260261

261-
log_config(args.verbosity, settings)
262+
logger = log_config(args.verbosity, settings)
262263
logger.debug(args)
263264
if args.help:
264265
parser.print_help()
@@ -306,7 +307,7 @@ def main(sys_args, when=None, settings=None):
306307
)
307308
return 0
308309

309-
formatter = core.Formatter(settings, args.format)
310+
formatter = when.formatter(args.format)
310311
try:
311312
results = when.results(
312313
args.timestr,

‎src/when/config.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@
3939
+------+--------------------------------------------------------------------------+--------------------------+------+
4040
| %M | Minute (00-59) | 55 | |
4141
+------+--------------------------------------------------------------------------+--------------------------+------+
42-
| %n | New-line character ('\n') | | + |
42+
| %n | New-line character | '\\n' | + |
4343
+------+--------------------------------------------------------------------------+--------------------------+------+
4444
| %p | AM or PM designation | PM | |
4545
+------+--------------------------------------------------------------------------+--------------------------+------+
@@ -49,7 +49,7 @@
4949
+------+--------------------------------------------------------------------------+--------------------------+------+
5050
| %S | Second (00-61) | 02 | |
5151
+------+--------------------------------------------------------------------------+--------------------------+------+
52-
| %t | Horizontal-tab character ('\t') | | + |
52+
| %t | Horizontal-tab character | '\\t' | + |
5353
+------+--------------------------------------------------------------------------+--------------------------+------+
5454
| %T | ISO 8601 time format (HH:MM:SS), equivalent to %H:%M:%S | 14:55:02 | + |
5555
+------+--------------------------------------------------------------------------+--------------------------+------+

‎src/when/core.py

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
from .db import client
1414
from .lunar import lunar_phase
1515

16-
logger = logging.getLogger(__name__)
16+
logger = utils.logger()
1717

1818

1919
def holidays(settings, co="US", ts=None):
@@ -59,9 +59,10 @@ def floating(m):
5959
mx = 2 + max(len(t[0]) for t in results)
6060
for title, dt in sorted(results, key=lambda o: o[1]):
6161
delta = dt - date.today()
62+
emoji, phase, age = lunar_phase(settings["lunar"], dt)
6263
print(
63-
"{:.<{}}{} ({} days) [{}]".format(
64-
title, mx, dt.strftime(holiday_fmt), delta.days, lunar_phase(settings["lunar"], dt)
64+
"{:.<{}}{} ({} days) [{} {}]".format(
65+
title, mx, dt.strftime(holiday_fmt), delta.days, emoji, phase
6566
)
6667
)
6768

@@ -128,7 +129,8 @@ def when_c(self, result):
128129

129130
def when_l(self, result):
130131
"Lunar phase emoji: 🌖"
131-
return lunar_phase(self.settings["lunar"], result.dt)
132+
emoji, phase, age = lunar_phase(self.settings["lunar"], result.dt)
133+
return f"{emoji} {phase}"
132134

133135
def c99_C(self, result):
134136
"Year divided by 100 and truncated to integer (00-99): 20"
@@ -201,7 +203,7 @@ def to_dict(self, dt=None):
201203
return {
202204
"name": self.name or self.zone_name(dt),
203205
"city": self.city.to_dict() if self.city else None,
204-
"utcoffset": [offset // 3600, offset % 3600 // 60, offset % 60],
206+
"utcoffset": [offset // 3600, offset % 3600 // 60],
205207
}
206208

207209
def zone_name(self, dt=None):
@@ -236,11 +238,13 @@ def __init__(self, dt, zone, source=None, offset=None):
236238
if offset:
237239
self.dt += offset
238240

239-
def to_dict(self):
241+
def to_dict(self, settings):
242+
emoji, phase, age = lunar_phase(settings["lunar"], self.dt)
240243
return {
241244
"iso": self.dt.isoformat(),
245+
"lunar": {"emoji": emoji, "phase": phase, "age": round(age, 5)},
242246
"zone": self.zone.to_dict(self.dt),
243-
"source": self.source.to_dict() if self.source else None,
247+
"source": self.source.to_dict(settings) if self.source else None,
244248
"offset": utils.format_timedelta(self.offset, short=True) if self.offset else None,
245249
}
246250

@@ -263,6 +267,9 @@ def __init__(self, settings, local_zone=None, db=None):
263267
self.local_zone = local_zone or TimeZoneDetail()
264268
self.errors = {}
265269

270+
def formatter(self, format="default", delta=None):
271+
return Formatter(self.settings, format=format, delta=delta)
272+
266273
def get_tz(self, name):
267274
value = self.tz_dict[name]
268275
return (utils.gettz(value), name)
@@ -363,7 +370,7 @@ def as_json(
363370
self, timestamp="", sources=None, targets=None, offset=None, exact=False, **json_kwargs
364371
):
365372
converts = self.results(timestamp, sources, targets, offset, exact)
366-
return json.dumps([convert.to_dict() for convert in converts], **json_kwargs)
373+
return json.dumps([convert.to_dict(self.settings) for convert in converts], **json_kwargs)
367374

368375
def grouped(self, results, offset=None):
369376
groups = {}

‎src/when/db/client.py

Lines changed: 20 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
from .. import utils
99
from ..exceptions import DBError
1010

11-
logger = logging.getLogger(__name__)
11+
logger = utils.logger()
1212

1313
DB_FILENAME = Path(__file__).parent / "when.db"
1414
DB_SCHEMA = """
@@ -41,7 +41,7 @@
4141
SELECT c.id, c.name, c.ascii, c.sub, c.co, c.tz
4242
FROM city c
4343
WHERE
44-
(c.id = :value OR c.name = :value OR c.ascii = :value)
44+
(c.id = :value OR UPPER(c.name) = :value OR UPPER(c.ascii) = :value)
4545
"""
4646

4747
ALIASES_LISTING_QUERY = """
@@ -165,6 +165,10 @@ def add_alias(self, name, gid):
165165
[(val.strip(), gid) for val in name.split(",")],
166166
)
167167

168+
@property
169+
def size(self):
170+
return self.filename.stat().st_size if self.filename.exists() else 0
171+
168172
@utils.timer
169173
def create_db(self, data, remove_existing=True):
170174
if self.filename.exists():
@@ -179,7 +183,7 @@ def create_db(self, data, remove_existing=True):
179183
cur.executemany("INSERT INTO city VALUES (?, ?, ?, ?, ?, ?, ?)", data)
180184
nrows = cur.rowcount
181185

182-
print(f"Inserted {nrows} rows")
186+
logger.info(f"Inserted {nrows:,} rows ({self.size:,} bytes)")
183187

184188
def _execute(self, con, sql, params):
185189
return con.execute(sql, params).fetchall()
@@ -192,29 +196,32 @@ def _search(self, sql, value, params):
192196
return City.from_results(results)
193197

194198
def parse_search(self, value):
195-
bits = [a.strip() for a in value.split(",")]
199+
bits = [a.strip().upper() for a in value.split(",")]
196200
nbits = len(bits)
197201
if nbits > 3:
198202
raise DBError(f"Invalid city search expression: {value}")
199203

200204
match nbits:
201205
case 1:
202-
return [value, None, None]
206+
return [bits[0], None, None]
203207
case 2:
204-
return [bits[0], bits[1], None]
208+
return [bits[0], None, bits[1]]
205209
case 3:
206210
return bits
207211

208212
def search(self, value, exact=False):
209-
value, co, sub = self.parse_search(value)
213+
value, sub, co = self.parse_search(value)
210214
if exact:
215+
data = {"value": value}
211216
sql = XSEARCH_QUERY
212217
if co:
213-
sql = f"{sql} AND c.co = :co AND c.sub = :sub" if sub else f"{sql} AND c.co = :co"
218+
data["co"] = co
219+
sql = f"{sql} AND UPPER(c.co) = :co"
220+
if sub:
221+
data["sub"] = sub
222+
sql = f"{sql} AND UPPER(c.sub) = :sub"
214223

215-
return self._search(
216-
sql, value, {"value": value, "co": co.upper() if co else co, "sub": sub}
217-
)
224+
return self._search(sql, value, data)
218225

219226
like_exprs = ["c.name LIKE :like", "c.ascii LIKE :like"]
220227
if co:
@@ -230,7 +237,7 @@ def search(self, value, exact=False):
230237
{
231238
"like": f"%{value}%",
232239
"value": value,
233-
"co": co.upper() if co else co,
234-
"sub": sub.upper() if sub else sub,
240+
"co": co,
241+
"sub": sub,
235242
},
236243
)

‎src/when/db/make.py

Lines changed: 44 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,35 @@
11
import io
2+
import time
23
import logging
34
import zipfile
4-
from collections import defaultdict
5+
from collections import defaultdict, namedtuple
56
from pathlib import Path
67

78
from .. import utils
89

9-
logger = logging.getLogger(__name__)
10+
logger = utils.logger()
11+
GeoCity = namedtuple(
12+
"GeoCity",
13+
"gid,"
14+
"name,"
15+
"aname,"
16+
"alt,"
17+
"lat,"
18+
"lng,"
19+
"fclass,"
20+
"fcode,"
21+
"co,"
22+
"cc2,"
23+
"a1,"
24+
"a2,"
25+
"a3,"
26+
"a4,"
27+
"pop,"
28+
"el,"
29+
"dem,"
30+
"tz,"
31+
"mod"
32+
)
1033

1134
DB_DIR = Path(__file__).parent
1235
GEONAMES_CITIES_URL_FMT = "https://download.geonames.org/export/dump/cities{}.zip"
@@ -27,7 +50,12 @@ def fetch_cities(size, dirname=DB_DIR):
2750
if txt_filename.exists():
2851
return txt_filename
2952

30-
zip_bytes = utils.fetch(GEONAMES_CITIES_URL_FMT.format(size))
53+
url = GEONAMES_CITIES_URL_FMT.format(size)
54+
logger.info(f"Beginning download from {url}")
55+
start = time.time()
56+
zip_bytes = utils.fetch(url)
57+
end = time.time()
58+
logger.info(f"Received {len(zip_bytes):,} bytes in {end-start:,}s")
3159
zip_filename = io.BytesIO(zip_bytes)
3260
with zipfile.ZipFile(zip_filename) as z:
3361
z.extract(txt_filename.name, txt_filename.parent)
@@ -77,49 +105,28 @@ def process_geonames_txt(fobj, minimum_population=15_000, admin_1=None):
77105
skip_if = {"PPL", "PPLL", "PPLS", "PPLF", "PPLR"}
78106
admin_1 = admin_1 or {}
79107
data = []
80-
i = 0
81-
for line in fobj:
108+
for i, line in enumerate(fobj, 1):
82109
i += 1
83-
(
84-
gid,
85-
name,
86-
aname,
87-
alt,
88-
lat,
89-
lng,
90-
fclass,
91-
fcode,
92-
co,
93-
cc2,
94-
a1,
95-
a2,
96-
a3,
97-
a4,
98-
pop,
99-
el,
100-
dem,
101-
tz,
102-
mod,
103-
) = line.rstrip().split("\t")
104-
105-
pop = int(pop) if pop else 0
110+
ct = GeoCity(*line.rstrip().split("\t"))
111+
112+
pop = int(ct.pop) if ct.pop else 0
106113
if (
107-
(fcode in skip)
108-
or (fcode in skip_if and (pop < minimum_population))
109-
or (fcode == "PPLA5" and name.startswith("Marseille") and name[-1].isdigit())
114+
(ct.fcode in skip)
115+
or (ct.fcode in skip_if and (pop < minimum_population))
116+
or (ct.fcode == "PPLA5" and ct.name.startswith("Marseille") and ct.name[-1].isdigit())
110117
):
111-
skipped[fcode] += 1
118+
skipped[ct.fcode] += 1
112119
continue
113120

114-
fcodes[fcode] += 1
115-
sub = admin_1.get(f"{co}.{a1}", a1)
116-
data.append([int(gid), name, aname, co, sub, tz, int(pop)])
121+
fcodes[ct.fcode] += 1
122+
sub = admin_1.get(f"{ct.co}.{ct.a1}", ct.a1)
123+
data.append([int(ct.gid), ct.name, ct.aname, ct.co, sub, ct.tz, pop])
117124

118125
for title, dct in [["KEPT", fcodes], ["SKIP", skipped]]:
119126
for k, v in sorted(dct.items(), key=lambda kv: kv[1], reverse=True):
120127
logger.debug(f"{title} {k:5}: {v}")
121128

122-
logger.debug(f"Processed {i} lines, kept {len(data)}")
129+
logger.info(f"Processed {i:,} lines, kept {len(data):,}")
123130
return data
124131

125132

@@ -139,5 +146,6 @@ def fetch_admin_1(dirname=DB_DIR):
139146
else:
140147
txt = utils.fetch(GEONAMES_ADMIN1_URL).decode()
141148
filename.write_text(txt)
149+
logger.info(f"Downloaded {len(txt):,} bytes from {GEONAMES_ADMIN1_URL}")
142150

143151
return load_admin1(txt)

‎src/when/lunar.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ def lunar_phase(settings, dt=None, dt_fmt=None):
2323

2424
emoji = settings["emojis"][index]
2525
name = settings["phases"][index]
26-
return f"{emoji} {name}"
26+
return emoji, name, age
2727

2828

2929
def full_moon_iterator(dt=None):

0 commit comments

Comments
 (0)