osmsg 1.0.2__tar.gz → 1.0.3__tar.gz

{osmsg-1.0.2 → osmsg-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: osmsg
-Version: 1.0.2
+Version: 1.0.3
 Summary: OpenStreetMap Stats Generator: Commandline
 Keywords: osm,stats,commandline,openstreetmap
 Author: Kshitij Raj Sharma
@@ -41,7 +41,8 @@ Description-Content-Type: text/markdown
 [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
 [![Container](https://img.shields.io/badge/ghcr.io-osgeonepal%2Fosmsg-2496ED?logo=docker)](https://github.com/osgeonepal/osmsg/pkgs/container/osmsg)
 
-**OpenStreetMap Stats Generator.** A tiny CLI (and Python library) that turns OSM history into per-user counts of nodes, ways, and relations created, modified, or deleted, written to parquet, csv, json, markdown, or Postgres.
+**OpenStreetMap Stats Generator.** A tiny CLI (and Python library) that turns OSM history into per-user counts
+of nodes, ways, and relations created, modified, or deleted, written to parquet, csv, json, markdown, or Postgres.
 
 A Project of [OSGeo Nepal](https://osgeonepal.org).
 
@@ -58,11 +59,15 @@ A Project of [OSGeo Nepal](https://osgeonepal.org).
 Pick the one that fits how you work.
 
 ```bash
+uvx --from osmsg osmsg --last hour       # zero-install, one-shot run
 pip install osmsg                        # into your project
 uv tool install osmsg                    # standalone CLI
 docker run --rm -v "$PWD:/work" -w /work ghcr.io/osgeonepal/osmsg:latest --last hour
 ```
 
+`uvx` can run osmsg in a throwaway environment , no install, no virtualenv to manage. Works
+with any flag combination, e.g. `uvx --from osmsg osmsg --last hour --tags building --summary -f parquet -f markdown`.
+
 ## Quick start
 
 ```bash
@@ -81,7 +86,8 @@ That's it. A `stats.duckdb` and a `stats.parquet` show up in your current folder
 osmsg --country nepal --last day
 ```
 
-`--country` resolves through Geofabrik and needs an OSM account. Set `OSM_USERNAME` and `OSM_PASSWORD` in your shell or a `.env` file:
+`--country` resolves through Geofabrik and needs an OSM account. Set `OSM_USERNAME` and `OSM_PASSWORD`
+in your shell or a `.env` file:
 
 ```bash
 export OSM_USERNAME=you
@@ -142,7 +148,8 @@ Any flag works as a YAML key. See [docs/Manual.md](./docs/Manual.md) for the ful
 
 ## Output formats
 
-Every run writes `stats.duckdb` (or `<--name>.duckdb`) plus the formats you ask for via `-f parquet|csv|json|markdown|psql`. Parquet is the default. Open it with duckdb, polars, pandas, anything.
+Every run writes `stats.duckdb` (or `<--name>.duckdb`) plus the formats you ask for via
+`-f parquet|csv|json|markdown|psql`. Parquet is the default. Open it with duckdb, polars, pandas, anything.
 
 ## Documentation
 
@@ -162,7 +169,8 @@ uv run pre-commit install
 uv run pytest -m "not network"
 ```
 
-Please read [CONTRIBUTING.md](./CONTRIBUTING.md) and the [Code of Conduct](./CODE_OF_CONDUCT.md) before opening a PR. Use [Conventional Commits](https://www.conventionalcommits.org/) (`cz commit`).
+Please read [CONTRIBUTING.md](./CONTRIBUTING.md) and the [Code of Conduct](./CODE_OF_CONDUCT.md) before opening a PR.
+Use [Conventional Commits](https://www.conventionalcommits.org/) (`cz commit`).
 
 ## License
 

{osmsg-1.0.2 → osmsg-1.0.3}/README.md

@@ -9,7 +9,8 @@
 [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
 [![Container](https://img.shields.io/badge/ghcr.io-osgeonepal%2Fosmsg-2496ED?logo=docker)](https://github.com/osgeonepal/osmsg/pkgs/container/osmsg)
 
-**OpenStreetMap Stats Generator.** A tiny CLI (and Python library) that turns OSM history into per-user counts of nodes, ways, and relations created, modified, or deleted, written to parquet, csv, json, markdown, or Postgres.
+**OpenStreetMap Stats Generator.** A tiny CLI (and Python library) that turns OSM history into per-user counts
+of nodes, ways, and relations created, modified, or deleted, written to parquet, csv, json, markdown, or Postgres.
 
 A Project of [OSGeo Nepal](https://osgeonepal.org).
 
@@ -26,11 +27,15 @@ A Project of [OSGeo Nepal](https://osgeonepal.org).
 Pick the one that fits how you work.
 
 ```bash
+uvx --from osmsg osmsg --last hour       # zero-install, one-shot run
 pip install osmsg                        # into your project
 uv tool install osmsg                    # standalone CLI
 docker run --rm -v "$PWD:/work" -w /work ghcr.io/osgeonepal/osmsg:latest --last hour
 ```
 
+`uvx` can run osmsg in a throwaway environment , no install, no virtualenv to manage. Works
+with any flag combination, e.g. `uvx --from osmsg osmsg --last hour --tags building --summary -f parquet -f markdown`.
+
 ## Quick start
 
 ```bash
@@ -49,7 +54,8 @@ That's it. A `stats.duckdb` and a `stats.parquet` show up in your current folder
 osmsg --country nepal --last day
 ```
 
-`--country` resolves through Geofabrik and needs an OSM account. Set `OSM_USERNAME` and `OSM_PASSWORD` in your shell or a `.env` file:
+`--country` resolves through Geofabrik and needs an OSM account. Set `OSM_USERNAME` and `OSM_PASSWORD`
+in your shell or a `.env` file:
 
 ```bash
 export OSM_USERNAME=you
@@ -110,7 +116,8 @@ Any flag works as a YAML key. See [docs/Manual.md](./docs/Manual.md) for the ful
 
 ## Output formats
 
-Every run writes `stats.duckdb` (or `<--name>.duckdb`) plus the formats you ask for via `-f parquet|csv|json|markdown|psql`. Parquet is the default. Open it with duckdb, polars, pandas, anything.
+Every run writes `stats.duckdb` (or `<--name>.duckdb`) plus the formats you ask for via
+`-f parquet|csv|json|markdown|psql`. Parquet is the default. Open it with duckdb, polars, pandas, anything.
 
 ## Documentation
 
@@ -130,7 +137,8 @@ uv run pre-commit install
 uv run pytest -m "not network"
 ```
 
-Please read [CONTRIBUTING.md](./CONTRIBUTING.md) and the [Code of Conduct](./CODE_OF_CONDUCT.md) before opening a PR. Use [Conventional Commits](https://www.conventionalcommits.org/) (`cz commit`).
+Please read [CONTRIBUTING.md](./CONTRIBUTING.md) and the [Code of Conduct](./CODE_OF_CONDUCT.md) before opening a PR.
+Use [Conventional Commits](https://www.conventionalcommits.org/) (`cz commit`).
 
 ## License
 

osmsg-1.0.3/osmsg/__version__.py

@@ -0,0 +1 @@
+__version__ = "1.0.3"

{osmsg-1.0.2 → osmsg-1.0.3}/osmsg/cli.py

@@ -194,6 +194,7 @@ def main(
         end_date=_parse_dt(end),
         countries=country,
         urls=url or ["minute"],
+        url_explicit=url is not None,
         workers=workers,
         additional_tags=tags,
         hashtags=hashtags,

{osmsg-1.0.2 → osmsg-1.0.3}/osmsg/export/markdown.py

@@ -80,8 +80,33 @@ def summary_markdown(
     parts.append(f"\nFull stats: `{fname}.parquet`")
 
     parts.append("\n#### Top 5 users")
+    user_cols = (
+        ("rank", "rank"),
+        ("name", "name"),
+        ("changesets", "changesets"),
+        ("map_changes", "map changes"),
+        ("nodes_create", "nodes created"),
+        ("ways_create", "ways created"),
+        ("rels_create", "rels created"),
+        ("poi_create", "poi created"),
+        ("hashtags", "hashtags"),
+    )
+    parts.append("| " + " | ".join(label for _, label in user_cols) + " |")
+    parts.append("| " + " | ".join("---" for _ in user_cols) + " |")
     for r in rows[:5]:
-        parts.append(f"- {r['name']}: {_human(int(r.get('map_changes', 0) or 0))} map changes")
+        cells: list[str] = []
+        for key, _ in user_cols:
+            v = r.get(key)
+            if key == "hashtags":
+                hts = v or []
+                cells.append(", ".join(hts[:3]) + (f" (+{len(hts) - 3})" if len(hts) > 3 else ""))
+            elif key == "name":
+                cells.append(str(v or ""))
+            elif key == "rank":
+                cells.append(str(v if v is not None else ""))
+            else:
+                cells.append(_human(int(v or 0)))
+        parts.append("| " + " | ".join(cells) + " |")
 
     if tm_stats and any("tasks_mapped" in r for r in rows):
         parts.append("\n#### Top 5 TM mappers")

{osmsg-1.0.2 → osmsg-1.0.3}/osmsg/pipeline.py

@@ -24,7 +24,7 @@ from .exceptions import CredentialsRequiredError, NoDataFoundError, OsmsgError
 from .export import summary_markdown, to_csv, to_json, to_parquet, to_psql
 from .fetch import download_osm_file
 from .geofabrik import country_update_url
-from .replication import ChangesetReplication, changefile_download_urls, resolve_url
+from .replication import SHORTCUTS, ChangesetReplication, changefile_download_urls, resolve_url
 from .ui import info, progress_bar, warn
 
 UTC = dt.UTC
@@ -49,6 +49,7 @@ class RunConfig:
     end_date: dt.datetime | None = None
     countries: list[str] | None = None
     urls: list[str] = field(default_factory=lambda: ["https://planet.openstreetmap.org/replication/minute"])
+    url_explicit: bool = False
     workers: int | None = None
     additional_tags: list[str] | None = None
     hashtags: list[str] | None = None
@@ -83,6 +84,34 @@ def _normalize_urls(cfg: RunConfig) -> None:
     cfg.urls = list(dict.fromkeys(resolve_url(u) for u in cfg.urls))
 
 
+def _pick_replication_for_span(span: dt.timedelta) -> str:
+    span_h = span.total_seconds() / 3600
+    if span_h < 6:
+        return "minute"
+    if span_h < 24 * 7:
+        return "hour"
+    return "day"
+
+
+def _auto_switch_replication(cfg: RunConfig, span: dt.timedelta) -> None:
+    """Swap a single planet-shortcut --url for the cheapest one that covers `span`."""
+    if cfg.url_explicit or cfg.update or cfg.countries or len(cfg.urls) != 1:
+        return
+    cur = cfg.urls[0]
+    if cur not in SHORTCUTS.values():
+        return
+    target_label = _pick_replication_for_span(span)
+    target_url = SHORTCUTS[target_label]
+    if target_url == cur:
+        return
+    cur_label = next(label for label, url in SHORTCUTS.items() if url == cur)
+    warn(
+        f"Span is {span}; auto-switching --url from '{cur_label}' to '{target_label}' to reduce load. "
+        f"Pass --url {cur_label} to keep '{cur_label}'."
+    )
+    cfg.urls = [target_url]
+
+
 def _canonical_hashtags(hashtags: list[str]) -> list[str]:
     # Force leading '#' so 'hotosm' and '#hotosm' both match the '#hotosm' tokens in changeset comments.
     return ["#" + h.lstrip("#") for h in hashtags]
@@ -96,7 +125,18 @@ def _resolve_url_starts(conn, cfg: RunConfig) -> dict[str, dt.datetime]:
         for url in cfg.urls:
             last = get_state(conn, url)
             if not last:
-                raise OsmsgError(f"--update has no prior state for {url}. Run osmsg without --update first to seed it.")
+                known = [r[0] for r in conn.execute("SELECT source_url FROM state").fetchall()]
+                hint = (
+                    f" Existing state in this DuckDB is for: {', '.join(known)}. "
+                    "Re-run --update with one of those URLs, or start fresh under a different --name."
+                    if known
+                    else " Run osmsg once without --update to seed state."
+                )
+                raise OsmsgError(
+                    f"--update cannot switch replication URL: no prior state for {url}.{hint} "
+                    "(Replaying the same window through a different granularity would double-count "
+                    "via the changeset_stats (seq_id, changeset_id) key.)"
+                )
             starts[url] = last["last_ts"]
         return starts
     if cfg.start_date is None:
@@ -219,14 +259,17 @@ def run(cfg: RunConfig) -> dict[str, Any]:
     dbmod.create_tables(conn)
     info(f"DuckDB: {db_path}")
 
+    if cfg.end_date is None:
+        cfg.end_date = dt.datetime.now(UTC)
+    if cfg.start_date is not None:
+        _auto_switch_replication(cfg, cfg.end_date - cfg.start_date)
+
     url_starts = _resolve_url_starts(conn, cfg)
     if cfg.update:
         # Changeset-replication reads one planet-wide source; widest window covers every URL.
         cfg.start_date = min(url_starts.values())
         info(f"--update: resuming each source from its own state row (earliest: {cfg.start_date.isoformat()})")
 
-    if cfg.end_date is None:
-        cfg.end_date = dt.datetime.now(UTC)
     # _resolve_url_starts guarantees start_date is set (or raised); narrow for ty.
     assert cfg.start_date is not None
     if cfg.start_date >= cfg.end_date:
@@ -235,8 +278,9 @@ def run(cfg: RunConfig) -> dict[str, Any]:
     span = cfg.end_date - cfg.start_date
     info(f"Range: {cfg.start_date.isoformat()} → {cfg.end_date.isoformat()} ({span})")
     span_hours = span.total_seconds() / 3600
-    # 72h on minute replication is ~4,300 files; beyond that, hour/day replication is much cheaper.
-    if span_hours >= 72 and any("minute" in u.lower() for u in cfg.urls):
+    # When auto-switch was suppressed (--url explicit, --update, --country, multi-URL), a long
+    # span on minute replication still floods the network. Hint the user.
+    if span_hours >= 72 and any(u == SHORTCUTS["minute"] for u in cfg.urls):
         warn(
             f"Range spans {span_hours:.0f}h on minute replication "
             f"(~{int(span_hours * 60):,} files). Consider --url hour or --url day."

{osmsg-1.0.2 → osmsg-1.0.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "osmsg"
-version = "1.0.2"
+version = "1.0.3"
 description = "OpenStreetMap Stats Generator: Commandline"
 readme = "README.md"
 authors = [

osmsg-1.0.2/osmsg/__version__.py

@@ -1 +0,0 @@
-__version__ = "1.0.2"