IssuesInventory(
username: str,
repo_name: str,
lazy: bool = False,
token: str | None = None,
use_cache: bool = True,
force_refresh: bool = False,
state: Literal["open", "closed", "all"] = "open",
filter_exprs: tuple[str | Expr, ...] = None,
select_exprs: tuple[str | Expr, ...] = None,
addcols_exprs: tuple[str | Expr, ...] = None,
show_tbl_cols: int | None = None,
show_tbl_rows: int | None = None,
)
Retrieve and parse a single GitHub repository’s Issues into a Polars DataFrame.
Provides optional Polars expression filters, selections, and addcols (DSL or native).
Usage Example:
inv = IssuesInventory("octocat", "Spoon-Knife", filter_exprs=["{state} == 'open'"])
df = inv.list_issues()
print(df)
username: GitHub username/org name.
repo_name: Name of the GitHub repository.
lazy: Whether to allow lazy Polars operations (applies to final DataFrame).
token: A GitHub token for higher rate limits.
use_cache: If True, use local cache before hitting GitHub.
force_refresh: If True, skip cache and refetch from GitHub.
state: Whether to get "open" issues (default), "closed", or both ("all").
filter_exprs: Polars expressions (str DSL or pl.Expr) to filter issues by.
select_exprs: Polars expressions (str DSL or pl.Expr) to select columns.
addcols_exprs: Polars expressions (str DSL or pl.Expr) to add computed columns.
show_tbl_cols: If set, configure Polars to print up to N columns.
show_tbl_rows: If set, configure Polars to print up to N rows.
Source code in src/octopols/issues.py
| def __init__(
self,
username: str,
repo_name: str,
lazy: bool = False,
token: str | None = None,
use_cache: bool = True,
force_refresh: bool = False,
state: Literal["open", "closed", "all"] = "open",
filter_exprs: tuple[str | pl.Expr, ...] = None,
select_exprs: tuple[str | pl.Expr, ...] = None,
addcols_exprs: tuple[str | pl.Expr, ...] = None,
show_tbl_cols: int | None = None,
show_tbl_rows: int | None = None,
) -> None:
"""Inventory of GitHub issues.
username: GitHub username/org name.
repo_name: Name of the GitHub repository.
lazy: Whether to allow lazy Polars operations (applies to final DataFrame).
token: A GitHub token for higher rate limits.
use_cache: If True, use local cache before hitting GitHub.
force_refresh: If True, skip cache and refetch from GitHub.
state: Whether to get "open" issues (default), "closed", or both ("all").
filter_exprs: Polars expressions (str DSL or pl.Expr) to filter issues by.
select_exprs: Polars expressions (str DSL or pl.Expr) to select columns.
addcols_exprs: Polars expressions (str DSL or pl.Expr) to add computed columns.
show_tbl_cols: If set, configure Polars to print up to N columns.
show_tbl_rows: If set, configure Polars to print up to N rows.
"""
self.username = username
self.repo_name = repo_name
self.lazy = lazy
self.token = token if token is not None else ENV_GH_TOKEN
self.use_cache = use_cache
self.force_refresh = force_refresh
self.state = state
# Convert all DSL or Expr inputs into Polars Expr
self.filter_exprs = tuple(map(prepare_expr, filter_exprs or []))
self.select_exprs = tuple(map(prepare_expr, select_exprs or []))
self.addcols_exprs = tuple(map(prepare_expr, addcols_exprs or []))
self._issues_df: pl.DataFrame | None = None
self._cache_dir = Path(user_cache_dir(appname="octopols.issues"))
self._cache_dir.mkdir(parents=True, exist_ok=True)
# e.g. "octocat_Spoon-Knife_issues.json"
self._cache_file = self._cache_dir / f"{username}_{repo_name}.json"
self._cfg = pl.Config()
if show_tbl_cols is not None:
self._cfg.set_tbl_cols(show_tbl_cols)
if show_tbl_rows is not None:
self._cfg.set_tbl_rows(show_tbl_rows)
|
list_issues
list_issues() -> pl.DataFrame
Fetch (and possibly cache) all issues from the given repository.
Apply any filter/select/addcols expressions. Return a Polars DataFrame.
If use_cache is True, tries reading from the local cache unless force_refresh.
If GitHub fetch fails, falls back to cache if available.
Source code in src/octopols/issues.py
| def list_issues(self) -> pl.DataFrame:
"""Fetch (and possibly cache) all issues from the given repository.
Apply any filter/select/addcols expressions. Return a Polars DataFrame.
If `use_cache` is True, tries reading from the local cache unless `force_refresh`.
If GitHub fetch fails, falls back to cache if available.
"""
if self._issues_df is not None:
return self._issues_df
self._issues_df = self._retrieve_issues()
return self._issues_df
|