Modules

An overview of the packages that make up olink. The API reference below is generated automatically from the source docstrings.

Core (olink.core)

Domain logic: git remote parsing, ecosystem detection, target definitions, the target registry, custom exceptions, and pinned-target persistence.

Project metadata: git remotes, ecosystem detection, package name extraction.

Git note: This module reads .git/config directly instead of calling git commands. This is faster but has limitations: - Supports [url “…”].insteadOf rewrites (longest-match prefix wins). - Does not support [include] directives in git config (no recursive merging). - Recognized platforms: github, gitlab, bitbucket, gitea, forgejo (incl. codeberg).

Hostname heuristic falls back when host is not the canonical SaaS one (self-hosted GitHub Enterprise, GitLab CE, Gitea, Forgejo).

• GitLab subgroups (e.g., group/subgroup/repo) are parsed as owner=”group” and repo=”subgroup/repo”. The generated URL https://host/group/subgroup/repo is correct for GitLab, but may not work for other platforms with nested paths.

class olink.core.project.EcosystemConfig(name, display_name, config_file, get_package_name, extra_signals=())

Bases: object

Configuration for an ecosystem.

config_file is the canonical filename (or glob) used by the simple existence check. extra_signals lists additional filename globs that also count as “ecosystem present” — used for ecosystems where multiple, equally-valid metadata layouts exist (e.g. CPAN’s Makefile.PL / dist.ini / lib/*.pm).

Parameters:

• name (str)

• display_name (str)

• config_file (str)

• get_package_name (Callable[[str], str])

• extra_signals (tuple[str, ...])

exists(cwd)

Check if this ecosystem’s config file (or any extra signal) exists.

Glob results are sorted so detection is deterministic across filesystems.

Parameters:

cwd (str)

Return type:

bool

class olink.core.project.ParsedRemote(platform, host, owner, repo)

Bases: object

Parsed git remote URL.

Parameters:

• platform (str)

• host (str)

• owner (str)

• repo (str)

property base_url: str

The base URL for this remote.

olink.core.project.detect_ecosystems(cwd)

Detect which ecosystems are present in the given directory.

Parameters:

cwd (str)

Return type:

list[str]

olink.core.project.get_open_vsx_name(cwd)

Build publisher.name extension id from package.json.

Open VSX (and VS Code Marketplace) identify extensions by publisher + name. Both fields required — raises ProjectMetadataError if either missing. Caller must split on ‘.’ to extract URL components.

Parameters:

cwd (str)

Return type:

str

olink.core.project.get_package_name(cwd, ecosystem)

Get the package name for a specific ecosystem.

Parameters:

• cwd (str)

• ecosystem (str)

Return type:

str

olink.core.project.get_remote_url(cwd, remote_name='origin')

Get the URL for a git remote, applying [url].insteadOf rewrites if configured.

Parameters:

• cwd (str)

• remote_name (str)

Return type:

str | None

olink.core.project.parse_remote_url(url)

Parse a git remote URL into its components.

Parameters:

url (str)

Return type:

ParsedRemote

All target definitions.

class olink.core.targets.ActionsTarget

Bases: GitPageTarget

Open the CI/CD page (Actions, Pipelines).

class olink.core.targets.BranchesTarget

Bases: GitPageTarget

Open the branches page.

class olink.core.targets.BundlephobiaTarget

Bases: Target

Open Bundlephobia (browser bundle size analyzer). Requires package.json.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.ClickPyTarget

Bases: Target

Open ClickPy ClickHouse-backed stats dashboard. Requires pyproject.toml.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.CodecovTarget

Bases: Target

Open the Codecov page for the project.

Codecov only integrates with GitHub, GitLab, and Bitbucket. Self-hosted forges (Gitea, Forgejo, Codeberg) are unsupported — raise rather than emit a 404 URL.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.CommitsTarget

Bases: GitPageTarget

Open the commit history.

class olink.core.targets.CoverallsTarget

Bases: Target

Open the Coveralls page for the project.

Coveralls only integrates with GitHub, GitLab, and Bitbucket. Self-hosted forges (Gitea, Forgejo, Codeberg) are unsupported — raise rather than emit a 404 URL.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.CpanTarget

Bases: Target

Surface MetaCPAN lookup for Perl dependencies from lightweight cpanfile metadata.

get_url(cwd)

Map the module name directly to MetaCPAN for immediate documentation and release access.

Parameters:

cwd (str)

Return type:

str

class olink.core.targets.CratesTarget

Bases: Target

Open crates.io crate page. Requires Cargo.toml with [package].name.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.DepsDevTarget(ecosystem=None)

Bases: MultiEcosystemTarget

Google deps.dev — dependency graph and security info.

Parameters:

ecosystem (str | None)

class olink.core.targets.DiscussionsTarget

Bases: GitPageTarget

Open the discussions page.

class olink.core.targets.DocsRsTarget

Bases: Target

Expose docs.rs so Rust users can jump directly to hosted API docs.

get_url(cwd)

Reuse Cargo metadata extraction to keep Rust naming logic consistent.

Parameters:

cwd (str)

Return type:

str

class olink.core.targets.EcosystemsTarget(ecosystem=None)

Bases: MultiEcosystemTarget

ecosyste.ms registry index. Uses host-style ecosystem slugs (pypi.org, npmjs.org).

Parameters:

ecosystem (str | None)

class olink.core.targets.GemsTarget

Bases: Target

Open rubygems.org gem page. Requires *.gemspec with spec.name = “…”.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.GitPageTarget

Bases: Target

Base for targets that open a specific page on the git hosting platform.

Subclasses set _page to a key in PLATFORM_URLS. Resolution raises UnsupportedFeatureError when the page is unavailable on the detected platform (e.g. discussions on GitLab).

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.GoDocsTarget

Bases: Target

Provide an intuitive alias for Go users who look for docs-oriented target names.

get_url(cwd)

Reuse go.mod module lookup so docs links match the canonical module identifier.

Parameters:

cwd (str)

Return type:

str

class olink.core.targets.GoPkgTarget

Bases: Target

Expose pkg.go.dev so Go maintainers can inspect published module docs.

get_url(cwd)

Link to the canonical Go package index used by most ecosystem tooling.

Parameters:

cwd (str)

Return type:

str

class olink.core.targets.HackageTarget

Bases: Target

Help Haskell maintainers inspect package metadata directly on Hackage.

get_url(cwd)

Reuse cabal package naming to avoid introducing Haskell-specific URL translation logic.

Parameters:

cwd (str)

Return type:

str

class olink.core.targets.HexTarget

Bases: Target

Open hex.pm (Elixir) package page. Uses OTP app: atom from mix.exs.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.InspectorTarget

Bases: Target

Open PyPI Inspector (browse package source/files). Requires pyproject.toml.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.IssuesTarget

Bases: GitPageTarget

Open the issues page.

class olink.core.targets.JsDelivrTarget

Bases: Target

Shortcut CDN package inspection for frontend dependency debugging workflows.

get_url(cwd)

Reuse npm package metadata so scoped names remain valid without extra mapping rules.

Parameters:

cwd (str)

Return type:

str

class olink.core.targets.LibRsTarget

Bases: Target

Open lib.rs (alternative crates.io browser, faster UX). Requires Cargo.toml.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.LibrariesIOTarget(ecosystem=None)

Bases: MultiEcosystemTarget

Libraries.io aggregate package page. Slugs match ecosystem keys 1:1.

Parameters:

ecosystem (str | None)

class olink.core.targets.MavenTarget

Bases: Target

Expose Maven Central pages for JVM artifacts based on standard project coordinates.

get_url(cwd)

Convert groupId/artifactId coordinates into Maven Central’s artifact URL format.

Parameters:

cwd (str)

Return type:

str

class olink.core.targets.MultiEcosystemTarget(ecosystem=None)

Bases: Target, ABC

Base class for targets that support multiple ecosystems.

Supports suffix notation: target:ecosystem e.g., snyk:pypi, deps:npm, libraries-io:cargo

Parameters:

ecosystem (str | None)

get_url(cwd)

Get the URL, auto-detecting ecosystem if not specified.

Parameters:

cwd (str)

Return type:

str

class olink.core.targets.NPMStatTarget

Bases: Target

Open npm-stat download charts. Uses ?package=<name> query string.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.NPMTarget

Bases: Target

Open npmjs.com package page. Handles scoped names (@org/pkg) via _encode_name.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.NuGetTarget

Bases: Target

Open NuGet (.NET) package page. Falls back to *.csproj filename when <PackageId> absent.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.OpenVSXTarget

Bases: Target

Enable extension authors to jump from local metadata straight to Open VSX listings.

get_url(cwd)

Use publisher + name from package.json because Open VSX identifies extensions by both.

Parameters:

cwd (str)

Return type:

str

class olink.core.targets.OriginTarget

Bases: Target

Open the remote origin URL.

Reads .git/config; raises NotGitRepoError outside a repo, NoRemoteError if ‘origin’ is not configured.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.PackagephobiaTarget

Bases: Target

Open Packagephobia (install size). Uses ?p=<name> query — urlencode handles scoped names.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.PackagistTarget

Bases: Target

Open Packagist PHP package page. Composer name format vendor/package preserved.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.PePyTarget

Bases: Target

Open PePy.tech download stats. Requires pyproject.toml.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.PiWheelsTarget

Bases: Target

Expose piwheels so Python projects can validate Raspberry Pi package availability.

get_url(cwd)

Reuse PyPI metadata lookup so package naming stays consistent across Python targets.

Parameters:

cwd (str)

Return type:

str

class olink.core.targets.PipTrendsTarget

Bases: Target

Open piptrends.com download trends. Requires pyproject.toml.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.PubTarget

Bases: Target

Open pub.dev (Dart/Flutter) package page. Requires pubspec.yaml.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.PullsTarget

Bases: GitPageTarget

Open the pull/merge requests page.

class olink.core.targets.PyPIJSONTarget

Bases: Target

Open the JSON API endpoint for the package — useful for CI scripts and metadata checks.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.PyPIStatsTarget

Bases: Target

Open pypistats.org download charts. Requires pyproject.toml.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.PyPITarget

Bases: Target

Open the canonical PyPI project page. Requires pyproject.toml with [project].name.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.ReleasesTarget

Bases: GitPageTarget

Open the releases page.

class olink.core.targets.RubyGemsStatsTarget

Bases: Target

Expose RubyGems usage stats to help maintainers gauge adoption quickly.

get_url(cwd)

Build on gemspec name extraction so package identity stays consistent across Ruby targets.

Parameters:

cwd (str)

Return type:

str

class olink.core.targets.SafetyDBTarget

Bases: Target

Open Safety DB vulnerability page for the PyPI package. Requires pyproject.toml.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.SecurityTarget

Bases: GitPageTarget

Open the security page.

class olink.core.targets.SkypackTarget

Bases: Target

Support quick compatibility checks against Skypack’s ESM package view.

get_url(cwd)

Derive URLs from npm metadata to keep behavior aligned with other JavaScript targets.

Parameters:

cwd (str)

Return type:

str

class olink.core.targets.SnykTarget(ecosystem=None)

Bases: MultiEcosystemTarget

Snyk security advisor. Snyk uses non-obvious slugs (npm-package, golang, rust).

Parameters:

ecosystem (str | None)

class olink.core.targets.SocketTarget(ecosystem=None)

Bases: MultiEcosystemTarget

Expose Socket.dev package risk pages across major ecosystems from one target.

Parameters:

ecosystem (str | None)

class olink.core.targets.Target

Bases: ABC

Base class for all targets.

Subclasses set name (CLI identifier) and description (help text), then implement get_url(cwd). Implementations MUST raise OlinkError subclasses (NoRemoteError, ProjectMetadataError, UnsupportedFeatureError) rather than generic exceptions — CLI relies on the hierarchy for user-facing messages.

abstract get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.UnpkgTarget

Bases: Target

Give maintainers a direct view of published npm artifacts as served by UNPKG.

get_url(cwd)

Use the package name from package.json so URL previews match published package IDs.

Parameters:

cwd (str)

Return type:

str

class olink.core.targets.UpstreamTarget

Bases: Target

Open the upstream remote URL (fork workflows where origin = your fork).

Raises NoRemoteError if ‘upstream’ remote is not configured.

get_url(cwd)

Return the URL to open for this target, given a project directory.

Parameters:

• cwd – Absolute path to the project root.

• cwd (str)

Raises:

OlinkError – Subclass appropriate to the failure (missing config, unsupported platform, etc.). Never a generic Exception.

Return type:

str

class olink.core.targets.WikiTarget

Bases: GitPageTarget

Open the wiki page.

olink.core.targets.get_platform_url(base_url, platform, page)

Get URL for a specific page on a platform.

Parameters:

• base_url (str)

• platform (str)

• page (str)

Return type:

str

Target catalog - explicit registration of all targets.

olink.core.catalog.get_target(name)

Get a target instance by name.

Supports suffix notation for multi-ecosystem targets: - “snyk” - auto-detect ecosystem - “snyk:pypi” - explicit Python ecosystem - “deps:npm” - explicit npm ecosystem

Parameters:

name (str)

Return type:

Target

olink.core.catalog.list_available_targets(cwd)

List targets available for the current project.

Returns (name, description, target_cls, ecosystem) tuples.

Parameters:

cwd (str)

Return type:

list[tuple[str, str, type[Target], str | None]]

olink.core.catalog.list_targets()

List all available targets with their descriptions.

Return type:

list[tuple[str, str]]

Custom exceptions for olink.

exception olink.core.exceptions.NoRemoteError

Bases: OlinkError

No git remote configured.

exception olink.core.exceptions.NotGitRepoError

Bases: OlinkError

Not inside a git repository.

exception olink.core.exceptions.OlinkError

Bases: Exception

Base exception for olink.

exception olink.core.exceptions.ProjectMetadataError

Bases: OlinkError

Could not read project metadata.

exception olink.core.exceptions.UnknownPlatformError

Bases: OlinkError

Unknown git hosting platform.

exception olink.core.exceptions.UnknownTargetError

Bases: OlinkError

Unknown target specified.

exception olink.core.exceptions.UnsupportedFeatureError

Bases: OlinkError

Feature not available on this platform.

Global pin persistence.

Pins are the first user-global state olink stores (everything else is derived from project files). Kept as a plain ordered JSON list so it can be edited by hand and rewritten from scratch. Failures here must never break the TUI, so read errors degrade to an empty list rather than raising.

olink.core.pins.config_dir()

Resolve olink’s config directory, honoring XDG_CONFIG_HOME.

Return type:

Path

olink.core.pins.load_pins()

Return pinned target names in order; empty on missing/corrupt/unreadable.

Return type:

list[str]

olink.core.pins.pins_file()

Path to the JSON file holding the ordered list of pinned target names.

Return type:

Path

olink.core.pins.save_pins(pins)

Write the pin list, creating the config directory if needed.

Writes to a sibling temp file and atomically renames it into place so a crash mid-write can never truncate pins.json (which load_pins would then silently read as an empty list, losing every pin).

Parameters:

pins (list[str])

Return type:

None

CLI (olink.cli)

Typer command-line interface.

CLI interface for olink.

olink.cli.app.main()

Entry point for the CLI.

Return type:

None

olink.cli.app.main_callback(target=<typer.models.ArgumentInfo object>, directory=<typer.models.OptionInfo object>, dry_run=<typer.models.OptionInfo object>, list_available_flag=<typer.models.OptionInfo object>, list_all_flag=<typer.models.OptionInfo object>, _version=<typer.models.OptionInfo object>)

Open external URLs related to your project.

Parameters:

• target (str | None)

• directory (str | None)

• dry_run (bool)

• list_available_flag (bool)

• list_all_flag (bool)

• _version (bool)

Return type:

None

TUI (olink.tui)

Textual terminal user interface.

Main TUI application.

class olink.tui.app.OlinkTUI(cwd)

Bases: App[None]

Main TUI application managing state and widget composition.

Create an instance of an app.

Parameters:

• driver_class – Driver class or None to auto-detect. This will be used by some Textual tools.

• css_path – Path to CSS or None to use the CSS_PATH class variable. To load multiple CSS files, pass a list of strings or paths which will be loaded in order.

• watch_css – Reload CSS if the files changed. This is set automatically if you are using textual run with the dev switch.

• ansi_color – Allow ANSI colors if True, or convert ANSI colors to RGB if False, None to use “ansi” parameter from themes.

• cwd (str)

Raises:

CssPathError – When the supplied CSS path(s) are an unexpected type.

BINDINGS: ClassVar[list[BindingType]] = [Binding(key='q', action='quit', description='Quit', show=True, key_display=None, priority=False, tooltip='', id=None, system=False, group=None), Binding(key='tab', action='toggle_mode', description='Toggle view', show=True, key_display=None, priority=True, tooltip='', id=None, system=False, group=None), Binding(key='o', action='open_target', description='Open', show=True, key_display=None, priority=False, tooltip='', id=None, system=False, group=None), Binding(key='c', action='copy_target', description='Copy', show=True, key_display=None, priority=False, tooltip='', id=None, system=False, group=None), Binding(key='p', action='toggle_pin', description='Pin', show=True, key_display=None, priority=False, tooltip='', id=None, system=False, group=None), Binding(key='slash', action='start_search', description='Search', show=False, key_display=None, priority=False, tooltip='', id=None, system=False, group=None), Binding(key='escape', action='cancel_search', description='Cancel search', show=False, key_display=None, priority=False, tooltip='', id=None, system=False, group=None)]

The default key bindings.

compose()

Yield child widgets for a container.

This method should be implemented in a subclass.

Return type:

Iterable[Widget]

action_start_search()

Show search input and focus it.

Return type:

None

action_cancel_search()

Cancel search, restore full list, refocus target list.

Return type:

None

on_input_changed(event)

Filter the target list as the user types in the search bar.

Parameters:

event (Changed)

Return type:

None

on_input_submitted(_event)

Confirm search: hide input, keep filtered list, refocus list.

Parameters:

_event (Submitted)

Return type:

None

action_toggle_pin()

Pin/unpin the highlighted target, persist, and keep it selected.

The app’s in-memory list is the session’s source of truth: we toggle it first, then try to persist. If the write fails the change still stands (surfaced as an error), and a later successful toggle cannot silently drop it by reloading a stale file from disk.

Return type:

None

olink.tui.app.launch_tui(cwd)

Entry point for the TUI.

Parameters:

cwd (str)

Return type:

None

Action handlers for the TUI.

olink.tui.actions.copy_to_clipboard(url)

Copy text to the system clipboard.

Parameters:

url (str)

Return type:

bool

olink.tui.actions.open_in_browser(url)

Open a URL in the default browser.

Parameters:

url (str)

Return type:

bool

Data models for the TUI.

class olink.tui.models.FilterState(mode='available')

Bases: object

Current TUI filter/view state.

Parameters:

mode (str)

class olink.tui.models.TargetItem(name, description, target_cls, ecosystem=None, pinned=False)

Bases: object

A target entry for display in the TUI.

Parameters:

• name (str)

• description (str)

• target_cls (type[Target])

• ecosystem (str | None)

• pinned (bool)

get_url(cwd)

Resolve the URL for this target.

Parameters:

cwd (str)

Return type:

str

olink.tui.models.build_all_targets()

Build list of all registered targets.

Return type:

list[TargetItem]

olink.tui.models.build_available_targets(cwd)

Build list of targets available for the current project.

Parameters:

cwd (str)

Return type:

list[TargetItem]

olink.tui.models.order_by_pins(items, pinned)

Return items pinned-first, marking each item’s pinned flag.

Pinned items come first in the order they appear in pinned; the rest keep their incoming order. Pin names absent from items are ignored, so in the TUI’s “available” mode a pin only surfaces when it applies to this project. This function mutates each input item’s pinned flag in place; it does not create copies.

Parameters:

• items (list[TargetItem])

• pinned (list[str])

Return type:

list[TargetItem]

Custom Textual widgets for the TUI.

class olink.tui.widgets.SearchInput

Bases: Input

Search bar that appears when / is pressed.

Initialise the Input widget.

Parameters:

• value – An optional default value for the input.

• placeholder – Optional placeholder text for the input.

• highlighter – An optional highlighter for the input.

• password – Flag to say if the field should obfuscate its content.

• restrict – A regex to restrict character inputs.

• type – The type of the input.

• max_length – The maximum length of the input, or 0 for no maximum length.

• suggester – [Suggester][textual.suggester.Suggester] associated with this input instance.

• validators – An iterable of validators that the Input value will be checked against.

• validate_on – Zero or more of the values “blur”, “changed”, and “submitted”, which determine when to do input validation. The default is to do validation for all messages.

• valid_empty – Empty values are valid.

• select_on_focus – Whether to select all text on focus.

• name – Optional name for the input widget.

• id – Optional ID for the widget.

• classes – Optional initial classes for the widget.

• disabled – Whether the input is disabled or not.

• tooltip – Optional tooltip.

• compact – Enable compact style (without borders).

DEFAULT_CSS: ClassVar[str] = '\n    SearchInput {\n        dock: bottom;\n        height: 1;\n        display: none;\n    }\n    '

Default TCSS.

can_focus: bool = True

Widget may receive focus.

can_focus_children: bool = True

Widget’s children may receive focus.

class olink.tui.widgets.StatusBar(content='', *, expand=False, shrink=False, markup=True, name=None, id=None, classes=None, disabled=False)

Bases: Static

Bottom status bar showing mode, count, and messages.

Initialize a Widget.

Parameters:

• *children – Child widgets.

• name – The name of the widget.

• id – The ID of the widget in the DOM.

• classes – The CSS classes for the widget.

• disabled – Whether the widget is disabled or not.

• markup – Enable content markup?

• content (VisualType)

• expand (bool)

• shrink (bool)

• markup (bool)

• name (str | None)

• id (str | None)

• classes (str | None)

• disabled (bool)

status_update(mode, count, total)

Update the status bar content.

Parameters:

• mode (str)

• count (int)

• total (int)

Return type:

None

set_error(message)

Show an error message.

Parameters:

message (str)

Return type:

None

set_success(message)

Show a success message.

Parameters:

message (str)

Return type:

None

can_focus: bool = False

Widget may receive focus.

can_focus_children: bool = True

Widget’s children may receive focus.

class olink.tui.widgets.TargetListWidget

Bases: ListView

Scrollable list of targets.

Initialize a ListView.

Parameters:

• *children – The ListItems to display in the list.

• initial_index – The index that should be highlighted when the list is first mounted.

• name – The name of the widget.

• id – The unique ID of the widget used in CSS/query selection.

• classes – The CSS classes of the widget.

• disabled – Whether the ListView is disabled or not.

BINDINGS: ClassVar[list[BindingType]] = [Binding(key='j', action='cursor_down', description='Down', show=False, key_display=None, priority=False, tooltip='', id=None, system=False, group=None), Binding(key='k', action='cursor_up', description='Up', show=False, key_display=None, priority=False, tooltip='', id=None, system=False, group=None)]

Key(s) | Description |

:- | :- |

enter | Select the current item. |

up | Move the cursor up. |

down | Move the cursor down. |

get_selected_item()

Get the currently highlighted target item.

Return type:

TargetItem | None

update_items(items)

Replace the list contents.

Parameters:

items (list[TargetItem])

Return type:

None

can_focus: bool = True

Widget may receive focus.

can_focus_children: bool = False

Widget’s children may receive focus.

class olink.tui.widgets.TargetRow(item)

Bases: ListItem

A single target row in the list.

Initialize a Widget.

Parameters:

• *children – Child widgets.

• name – The name of the widget.

• id – The ID of the widget in the DOM.

• classes – The CSS classes for the widget.

• disabled – Whether the widget is disabled or not.

• markup – Enable content markup?

• item (TargetItem)

compose()

Called by Textual to create child widgets.

This method is called when a widget is mounted or by setting recompose=True when calling [refresh()][textual.widget.Widget.refresh].

Note that you don’t typically need to explicitly call this method.

Example

```python def compose(self) -> ComposeResult:

yield Header() yield Label(“Press the button below:”) yield Button() yield Footer()

```

Return type:

Iterable[Widget]

can_focus: bool = False

Widget may receive focus.

can_focus_children: bool = True

Widget’s children may receive focus.