calkit-python 0.47.11__tar.gz → 0.47.12__tar.gz

{calkit_python-0.47.11 → calkit_python-0.47.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: calkit-python
-Version: 0.47.11
+Version: 0.47.12
 Summary: Reproducibility simplified.
 Project-URL: Homepage, https://calkit.org
 Project-URL: Issues, https://github.com/calkit/calkit/issues

{calkit_python-0.47.11 → calkit_python-0.47.12}/calkit/cli/check.py

@@ -1458,12 +1458,16 @@ def check_docker_env(
                     # Leaving the tag would fake a registry digest on the
                     # image, making every later push look unnecessary
                     ck_docker.untag_image(remote_ref)
+                    hint = ck_docker.registry_login_hint(
+                        remote_ref, push_output
+                    )
                     warn(
                         f"Failed to push image to {remote_ref}; its lock "
                         "file will record no digest, so anyone else who "
                         "uses this project will rebuild this image rather "
                         "than pull it\n"
                         + textwrap.indent(push_output.strip()[-500:], "    ")
+                        + (f"\n{hint}" if hint else "")
                     )
         identity = dict(identity, RepoDigests=remote_digests)
     elif fpath is None:

{calkit_python-0.47.11 → calkit_python-0.47.12}/calkit/cli/main/core.py

@@ -1780,9 +1780,13 @@ def push(
             if not success:
                 # Leaving the tag would fake a registry digest on the image
                 calkit.docker.untag_image(remote_ref)
+                hint = calkit.docker.registry_login_hint(
+                    remote_ref, push_output
+                )
                 warn(
                     f"Failed to push image to {remote_ref}\n"
                     + textwrap.indent(push_output.strip()[-500:], "    ")
+                    + (f"\n{hint}" if hint else "")
                 )
     if "git" in selected:
         typer.echo("Pushing to Git remote")

{calkit_python-0.47.11 → calkit_python-0.47.12}/calkit/docker.py

@@ -1144,6 +1144,35 @@ def is_auth_error(output: str) -> bool:
     return any(marker in lowered for marker in _AUTH_ERROR_MARKERS)
 
 
+def registry_login_hint(ref: str, output: str) -> str:
+    """Return how to log in to a registry that refused a push, or ''.
+
+    Calkit walks the user through creating a token itself when it can
+    prompt, so this is for when it can't: a push from a pipeline, a script
+    or an agent would otherwise end on the registry's bare "unauthorized",
+    which says nothing about what to do next.
+    """
+    if not is_auth_error(output):
+        return ""
+    host = ref.split("/", 1)[0]
+    if host != "ghcr.io":
+        return (
+            f"{host} refused the push; log Docker in to it with "
+            f"'docker login {host}' and push again"
+        )
+    return (
+        "The GitHub Container Registry refused the push: no credential "
+        "Calkit has can write packages. To fix this, either:\n"
+        "  - run 'calkit push docker' in a terminal, which walks you "
+        "through creating a token and remembers it; or\n"
+        "  - create a token with the 'write:packages' scope at\n"
+        f"      {GITHUB_PACKAGES_TOKEN_URL}\n"
+        "    log Docker in with it, pasting the token as the password:\n"
+        f"      docker login ghcr.io -u {get_github_username()}\n"
+        "    and push again with 'calkit push docker'"
+    )
+
+
 def get_github_token_scopes(token: str) -> set[str]:
     """Return the OAuth scopes a GitHub token carries.
 

{calkit_python-0.47.11 → calkit_python-0.47.12}/calkit/latex.py

@@ -55,7 +55,7 @@ WORKING_NAME = "working"
 # of a full TeX Live image. Pinned to an exact tag rather than :latest so
 # a document keeps building against the same TeX until this is moved
 # deliberately; what it carries is recorded in images/latex/README.md.
-DEFAULT_LATEX_IMAGE = "ghcr.io/calkit/latex:0.1.4"
+DEFAULT_LATEX_IMAGE = "ghcr.io/calkit/latex:0.1.5"
 # The environment created for a document that doesn't have one, wherever
 # that happens: a new publication, an Overleaf import, or a stage whose
 # environment is worked out from what it runs. Copied where it's used,

{calkit_python-0.47.11 → calkit_python-0.47.12}/calkit/questions.py

@@ -248,6 +248,17 @@ class _Formatter(string.Formatter):
             raise KeyError(field_name)
         return kwargs[field_name], field_name
 
+    def format_field(self, value: Any, format_spec: str) -> Any:
+        # A value the spec can't format, e.g., a null under ':.2f', raises
+        # TypeError, which callers don't expect; as ValueError it is
+        # reported as a template that cannot render rather than a crash
+        try:
+            return super().format_field(value, format_spec)
+        except TypeError as e:
+            raise ValueError(
+                f"{value!r} cannot be formatted as {format_spec!r}"
+            ) from e
+
 
 _FORMATTER = _Formatter()
 _PLACEHOLDER = re.compile(r"(?<!\{)\{([^{}:!]+)(?:[:!][^{}]*)?\}(?!\})")
@@ -933,8 +944,7 @@ def _check_publication_label(
     sources = _find_latex_sources(ev["path"], ck_info, wdir)
     if not sources:
         return "skipped", (
-            f"label {label!r} not checked: no LaTeX stage produces "
-            f"{ev['path']}"
+            f"label {label!r} not checked: no LaTeX stage produces {ev['path']}"
         )
     pattern = re.compile(r"\\label\{" + re.escape(label) + r"\}")
     for src in sources:

{calkit_python-0.47.11 → calkit_python-0.47.12}/calkit/resources/devcontainer/devcontainer.json

@@ -31,7 +31,7 @@
       "settings": {
         "latex-workshop.bibtex-format.tab": "4 spaces",
         "latex-workshop.latex.autoBuild.run": "onSave",
-        "latex-workshop.docker.image.latex": "ghcr.io/calkit/latex:0.1.4",
+        "latex-workshop.docker.image.latex": "ghcr.io/calkit/latex:0.1.5",
         "latex-workshop.docker.enabled": true,
         "dvc.doNotShowSetupAfterInstall": true,
         "workbench.editorAssociations": {

{calkit_python-0.47.11 → calkit_python-0.47.12}/calkit/resources/vscode/settings.json

@@ -1,7 +1,7 @@
 {
   "latex-workshop.bibtex-format.tab": "4 spaces",
   "latex-workshop.latex.autoBuild.run": "onSave",
-  "latex-workshop.docker.image.latex": "ghcr.io/calkit/latex:0.1.4",
+  "latex-workshop.docker.image.latex": "ghcr.io/calkit/latex:0.1.5",
   "latex-workshop.docker.enabled": true,
   "dvc.doNotShowSetupAfterInstall": true,
   "workbench.editorAssociations": {

{calkit_python-0.47.11 → calkit_python-0.47.12}/calkit/tests/test_docker.py

@@ -351,6 +351,30 @@ def test_is_auth_error():
     assert not is_auth_error("")
 
 
+def test_registry_login_hint(monkeypatch):
+    import calkit.docker
+
+    monkeypatch.setattr(
+        calkit.docker, "get_github_username", lambda: "someone"
+    )
+    ref = "ghcr.io/o/p/img:latest"
+    # A refusal from GHCR says how to get a token that can push, since a
+    # push that can't prompt otherwise ends on a bare "unauthorized"
+    hint = calkit.docker.registry_login_hint(
+        ref, "error from registry: unauthorized"
+    )
+    assert calkit.docker.GITHUB_PACKAGES_TOKEN_URL in hint
+    assert "docker login ghcr.io -u someone" in hint
+    assert "calkit push docker" in hint
+    # Another registry gets only what Calkit knows: log in to it
+    hint = calkit.docker.registry_login_hint(
+        "docker.io/someone/img:v1", "unauthorized: authentication required"
+    )
+    assert "docker login docker.io" in hint
+    # Anything other than refused credentials is no login problem
+    assert calkit.docker.registry_login_hint(ref, "manifest unknown") == ""
+
+
 def test_login_to_registry_ignores_other_registries():
     # Only GHCR has credentials Calkit can obtain; everything else relies
     # on the user's own docker login

{calkit_python-0.47.11 → calkit_python-0.47.12}/calkit/tests/test_questions.py

@@ -70,6 +70,14 @@ def test_render():
         render("{missing}", values)
     with pytest.raises(ValueError):
         render("{best:.2f}", values)
+    # A value the spec can't take at all, e.g., a null, is a ValueError
+    # too, not a TypeError nothing expects
+    for bad in (None, {"a": 1}):
+        with pytest.raises(ValueError, match="cannot be formatted"):
+            render("{x:.2f}", {"x": bad})
+    # The check reports it as a problem rather than crashing
+    problems = calkit.questions._placeholder_problems("{x:.2f}", {"x": None})
+    assert problems and "cannot render" in problems[0]
 
 
 def _commit(msg: str) -> str:

{calkit_python-0.47.11 → calkit_python-0.47.12}/docs/comparisons.md

@@ -129,6 +129,72 @@ Calkit isn't limited to one article, layout, or kind of environment,
 and its questions state claims apart from any document,
 with the check reporting stale or untraceable evidence.
 
+## Project templates
+
+A template repository starts a project from a fixed layout,
+not from a tool you install.
+[The Turing Way's reproducible project template](https://github.com/the-turing-way/reproducible-project-template)
+is a GitHub template repo with folders for `data`, `models`, `src`,
+`notebooks`, `reports`, and `project-management`,
+plus the files a project is expected to have:
+a README, a license, a code of conduct, contribution guidelines, and
+issue templates.
+It's about repository hygiene,
+and nothing in it runs the project.
+
+[Cookiecutter Data Science](https://cookiecutter-data-science.drivendata.org/)
+is the data science equivalent, generated with `ccds`.
+It asks which environment manager, dependency file, testing framework,
+linter, docs, license, and dataset storage to use,
+then writes a `pyproject.toml`, a Makefile, and a Python package with
+modules for data, features, modeling, and plots.
+Its docs hold that analysis is a DAG and raw data is immutable,
+and the Makefile has targets like `make requirements`, `make test`, and
+`make data`,
+but wiring the graph up is left to the user,
+with Make, Airflow, Luigi, and Snakemake suggested.
+
+The [TU Delft Jupyter Book starterkit](https://github.com/TUD-JB-OS/starterkit)
+starts from the other end, the document.
+A GitHub Action builds a MyST site and a PDF on every push,
+and a `pixi` environment and lock file are included to build them
+locally.
+It's for a thesis, so its content is chapters,
+one of which is a notebook that renders into the book,
+and it includes an analysis stack, e.g., NumPy and Matplotlib.
+
+None gives single-button reproducibility.
+The starterkit builds the document in one command,
+and ccds gives you a few convenience targets,
+but no template declares the analysis as a graph of stages,
+so nothing skips a step whose inputs haven't changed,
+and nothing reports an output that's out of date.
+showyourwork gets closer, since it builds the article from a
+Snakemake workflow and reruns it on every push,
+but it does that with tooling of its own rather than by including
+other tools' config.
+With the templates, reproducibility is a property the user maintains
+by hand.
+
+The templates do keep code, notebooks, models, and reports in one
+repository,
+which is a shared home rather than a silo,
+and better than splitting the analysis and the writing across separate
+repos or apps.
+What they don't provide is the vertical integration.
+Nothing declares how the writing and the analysis relate,
+so a figure or number in the report is placed there by hand,
+not read from an output,
+and the report can drift from the analysis it's meant to describe.
+Cookiecutter Data Science also keeps data out of the repository,
+syncing it to cloud storage or Git LFS,
+with no record in the project of which data produced which output.
+Calkit declares the environments, the pipeline, and the publication
+together,
+so a change to the data reruns what depends on it,
+and a question's answer is read from the pipeline output that computes
+it.
+
 ## Environment management
 
 Tools like conda, uv, pixi, renv, Docker, and Julia's package manager

{calkit_python-0.47.11 → calkit_python-0.47.12}/docs/pipeline/index.md

@@ -34,7 +34,7 @@ environments:
     python: "3.13"
   texlive:
     kind: docker
-    image: ghcr.io/calkit/latex:0.1.4
+    image: ghcr.io/calkit/latex:0.1.5
 
 # Define the pipeline
 pipeline:

{calkit_python-0.47.11 → calkit_python-0.47.12}/docs/privacy.md

@@ -1,6 +1,6 @@
 # Privacy policy
 
-Last updated: 2026-09-14
+Last updated: 2026-09-29
 
 This covers the Calkit hub at [calkit.io](https://calkit.io), the Calkit
 command line tool and Python package, and the Calkit browser extension.
@@ -11,10 +11,11 @@ Calkit is run by Pete Bachant as a sole proprietor, who is responsible for
 the information described here. Questions and requests go to
 [help@calkit.io](mailto:help@calkit.io).
 
-The short version: we keep what's needed to run your account, and, only if
-you allow it, a record of which features you use so we can make Calkit
-better. Your data is never sold, never used for advertising, and never
-shared with anyone for their own purposes.
+The short version: we keep what's needed to run your account, count
+anonymous page views to see how the site is used, and, only if you allow
+it, keep a record of which features you use so we can make Calkit better.
+Your data is never sold, never used for advertising, and never shared with
+anyone for their own purposes.
 
 ## How usage information is used
 
@@ -47,20 +48,33 @@ watch what any one person is doing.
 
 ### Usage information
 
-When you first visit the hub, it asks whether you allow usage information
-to be recorded. If you accept, the hub records the pages you visit and the
-features you use, along with basic browser and device information and an
-approximate location derived from your IP address. While you're signed in,
-this is associated with your account, and includes actions recorded by the
-hub's server, such as creating a project or publishing a release.
-
-If you reject, none of it is recorded, and nothing for this purpose is
+The hub always counts anonymous page views, and keeps fuller usage
+information only if you allow it.
+
+Anonymous page views record which pages are opened, when, and whether the
+visit looks like a person rather than a bot. They are not linked to your
+account, no identifier is stored on your device, and no IP address is sent
+to our analytics provider, so they can't be traced back to you. The hub
+briefly uses your IP address and browser's user agent to tell one day's
+visits apart, then discards them. These counts are used only to see how
+much each part of the site is used.
+
+When you first visit, the hub also asks whether you allow fuller usage
+information to be recorded. If you accept, page views stop being anonymous
+and the hub records the pages you visit and the features you use, along with
+an approximate location derived from your IP address. While you're signed
+in, this is associated with your account, and includes actions recorded by
+the hub's server, such as creating a project or publishing a release.
+
+If you reject, only the anonymous page views described above are kept; none
+of the fuller information is recorded, and nothing for this purpose is
 stored on your device. Once you're signed in, your choice is saved to your
 account, so it applies on every device you use.
 
 You can change your choice at any time under Settings → Privacy. Stopping
-it stops future recording. To have usage information that was already
-recorded deleted, email [help@calkit.io](mailto:help@calkit.io).
+it stops future recording of the fuller information. To have usage
+information that was already recorded deleted, email
+[help@calkit.io](mailto:help@calkit.io).
 
 ### Server logs
 
@@ -89,8 +103,10 @@ governed by that service's policy.
 
 - **Account information and your work**: needed to provide the service you
   signed up for.
-- **Usage information**: only with your consent, which you can withdraw at
-  any time.
+- **Anonymous page views**: our legitimate interest in understanding how the
+  site is used, without identifying you or storing anything on your device.
+- **Fuller usage information**: only with your consent, which you can
+  withdraw at any time.
 - **Server logs**: our legitimate interest in keeping the service running
   and secure.
 

{calkit_python-0.47.11 → calkit_python-0.47.12}/docs/tutorials/existing-project.md

@@ -377,7 +377,7 @@ The project also compiles some LaTeX documents.
 We can create a Docker environment called `tex` for these with:
 
 ```sh
-calkit new docker-env --name tex --image ghcr.io/calkit/latex:0.1.4
+calkit new docker-env --name tex --image ghcr.io/calkit/latex:0.1.5
 ```
 
 This environment uses Calkit's LaTeX Docker image,

{calkit_python-0.47.11 → calkit_python-0.47.12}/hub/backend/app/api/main.py

@@ -2,6 +2,7 @@ from fastapi import APIRouter
 
 from app.api.routes import (
     accounts,
+    analytics,
     datasets,
     feedback,
     login,
@@ -15,6 +16,7 @@ from app.api.routes.projects import releases
 
 api_router = APIRouter()
 api_router.include_router(accounts.router, tags=["accounts"])
+api_router.include_router(analytics.router, tags=["analytics"])
 api_router.include_router(login.router, tags=["login"])
 api_router.include_router(users.router, tags=["users"])
 api_router.include_router(misc.router, tags=["misc"])

calkit_python-0.47.12/hub/backend/app/api/routes/analytics.py

@@ -0,0 +1,196 @@
+"""Receive anonymous page views.
+
+Page views are counted here rather than in the browser so that nothing has to
+be stored on the visitor's device, which is what lets them be collected
+without consent. The visitor is identified for the day by a keyed hash of the
+request's IP address and user agent, which groups one visitor's views for the
+day without being linkable across days; the raw values are never kept.
+"""
+
+import hashlib
+import hmac
+import re
+
+from fastapi import (
+    APIRouter,
+    BackgroundTasks,
+    HTTPException,
+    Request,
+    Response,
+)
+from pydantic import BaseModel, Field, ValidationError
+
+from app import cache, mixpanel
+from app.config import settings
+from app.core import utcnow
+
+router = APIRouter()
+
+# A batch is what the browser accumulated between flushes, which is bounded on
+# that side too; the cap here is what stops a crafted request from fanning out
+# into unbounded work. Paths are route templates, so they are short.
+MAX_VIEWS_PER_REQUEST = 20
+MAX_PATH_LENGTH = 200
+MAX_NAME_LENGTH = 100
+MAX_BODY_BYTES = 64 * 1024
+
+# The browser sends a batch at most every 15 seconds, so this is far more than
+# a real session needs while still bounding what one address can do. The
+# endpoint is unauthenticated and fans out into outbound calls, so without
+# this a small flood could tie up workers and run up analytics cost.
+RATE_LIMIT_REQUESTS = 60
+RATE_LIMIT_WINDOW_SECONDS = 60
+
+# User agents that name themselves as crawlers or command-line clients. Bots
+# driving a real browser don't show up here, which is why the interaction
+# signal exists.
+_BOT_UA_RE = re.compile(
+    r"bot|crawl|spider|slurp|curl|wget|python|httpclient|scrapy|headless|"
+    r"phantom|selenium|puppeteer|playwright|lighthouse|pingdom|uptimerobot|"
+    r"facebookexternalhit|monitor|preview",
+    re.IGNORECASE,
+)
+
+
+class PageViewIn(BaseModel):
+    # The page's resolved path, e.g., "/pete/proj/datasets", with any secret
+    # parameter, e.g., an invitation token, left as its placeholder
+    path: str = Field(max_length=MAX_PATH_LENGTH)
+    # The owner and project a project page belongs to; names, not secrets,
+    # which is what lets interest in a project be measured
+    owner_name: str | None = Field(default=None, max_length=MAX_NAME_LENGTH)
+    project_name: str | None = Field(default=None, max_length=MAX_NAME_LENGTH)
+    # Milliseconds between the view and the batch being sent
+    dwell_ms: int = Field(default=0, ge=0)
+
+
+class SignalsIn(BaseModel):
+    # Whether the browser was driven (navigator.webdriver)
+    webdriver: bool = False
+    # Whether any real input, e.g., a pointer, key, or scroll, happened; a
+    # bot that only loads pages reports none
+    interacted: bool = False
+
+
+class PageViewsIn(BaseModel):
+    views: list[PageViewIn] = Field(max_length=MAX_VIEWS_PER_REQUEST)
+    signals: SignalsIn = Field(default_factory=SignalsIn)
+
+
+def _client_ip(request: Request) -> str:
+    # Behind the proxy the socket address is the proxy's, so the forwarded
+    # headers are what actually name the visitor
+    for header in ("cf-connecting-ip", "x-real-ip"):
+        value = request.headers.get(header)
+        if value:
+            return value.strip()
+    forwarded = request.headers.get("x-forwarded-for")
+    if forwarded:
+        return forwarded.split(",")[0].strip()
+    return request.client.host if request.client else ""
+
+
+def _visitor_id(request: Request) -> str:
+    """A per-day identifier derived from the request alone.
+
+    The date is mixed in so the same visitor gets a new identifier each day,
+    which is what keeps their views from being linkable over time, and the
+    secret keeps the value from being reversed without it.
+    """
+    material = "|".join(
+        [
+            utcnow().date().isoformat(),
+            _client_ip(request),
+            request.headers.get("user-agent", ""),
+        ]
+    )
+    digest = hmac.new(
+        settings.SECRET_KEY.encode(), material.encode(), hashlib.sha256
+    ).hexdigest()
+    return digest[:32]
+
+
+def _is_bot(signals: SignalsIn, user_agent: str) -> bool:
+    return signals.webdriver or bool(_BOT_UA_RE.search(user_agent))
+
+
+def _rate_limited(ip: str) -> bool:
+    """Whether this address has used up its allowance.
+
+    Counted in the shared cache so the limit holds across API workers. If the
+    cache is unavailable the request goes through: analytics is not worth
+    failing a page over, and the caps on body size and views still bound the
+    work.
+    """
+    client = cache.get_client()
+    if client is None:
+        return False
+    key = f"pageviews:{ip}"
+    try:
+        count = client.incr(key)
+        if count == 1:
+            client.expire(key, RATE_LIMIT_WINDOW_SECONDS)
+        return count > RATE_LIMIT_REQUESTS
+    except Exception:
+        return False
+
+
+def _record(
+    visitor_id: str,
+    views: list[PageViewIn],
+    bot: bool,
+    interacted: bool,
+) -> None:
+    for view in views:
+        mixpanel.track_anonymous_pageview(
+            visitor_id=visitor_id,
+            path=view.path,
+            bot=bot,
+            interacted=interacted,
+            dwell_ms=view.dwell_ms,
+            owner_name=view.owner_name,
+            project_name=view.project_name,
+        )
+
+
+@router.post("/pageviews", status_code=204, include_in_schema=False)
+async def post_pageviews(
+    request: Request, background_tasks: BackgroundTasks
+) -> Response:
+    """Record a batch of anonymous page views.
+
+    Deliberately unauthenticated: the visitor is not signed in for this
+    purpose, and the request carries no identifier of its own. The browser
+    sends this as a `text/plain` beacon, so the body is parsed by hand rather
+    than through a JSON content type, which a cross-origin beacon could not
+    set without a preflight. Sending to Mixpanel happens after the response,
+    since a beacon has nobody waiting on it.
+    """
+    if not settings.MIXPANEL_TOKEN:
+        return Response(status_code=204)
+    ip = _client_ip(request)
+    if _rate_limited(ip):
+        raise HTTPException(429, "Too many requests")
+    content_length = request.headers.get("content-length")
+    if (
+        content_length
+        and content_length.isdigit()
+        and int(content_length) > MAX_BODY_BYTES
+    ):
+        raise HTTPException(413, "Batch too large")
+    body = await request.body()
+    if len(body) > MAX_BODY_BYTES:
+        raise HTTPException(413, "Batch too large")
+    try:
+        payload = PageViewsIn.model_validate_json(body)
+    except ValidationError:
+        raise HTTPException(422, "Invalid page view batch")
+    user_agent = request.headers.get("user-agent", "")
+    background_tasks.add_task(
+        _record,
+        _visitor_id(request),
+        payload.views,
+        _is_bot(payload.signals, user_agent),
+        payload.signals.interacted,
+    )
+    return Response(status_code=204)

{calkit_python-0.47.11 → calkit_python-0.47.12}/hub/backend/app/api/routes/projects/core.py

@@ -117,6 +117,7 @@ from app.git import (
     record_project_update,
     resolve_commit_sha,
     search_refs,
+    seed_shared_read_clone,
 )
 from app.models import (
     Account,
@@ -1183,6 +1184,7 @@ def post_project(
                 commit_msg = "Create README.md, DVC config, and calkit.yaml"
             repo.git.commit(["-m", commit_msg])
             push_and_expire(project, repo)
+            seed_shared_read_clone(project, repo)
         except Exception as e:
             # The project row is already committed, and it would block a retry
             # since a Git repo can only back one project, so remove it and let