ID Sampler

The ID-based sampler uses GitHub’s sequential repository ID system to generate truly random samples by probing random IDs from the valid ID range.

class reporoulette.IDSampler(token=None, min_id=1, max_id=1300000000, rate_limit_safety=100, seed=None, log_level=20)[source]

Bases: BaseSampler

Sample repositories using random ID probing.

This sampler generates random repository IDs within a specified range and attempts to retrieve repositories with those IDs from GitHub. The resulting sample is approximately uniform over all existing public repositories with ID <= max_id.

Parameters:

  • token (str | None)

  • min_id (int)

  • max_id (int)

  • rate_limit_safety (int)

  • seed (int | None)

  • log_level (int)

DEFAULT_MAX_ID = 1300000000
update_max_id()[source]

Refresh max_id from the newest repository visible on GitHub.

Makes one search API call for repositories created in the last day and sets max_id to the highest ID observed (approximately the current ID ceiling). Falls back to the existing max_id with a warning if the call fails.

Returns:

The (possibly updated) max_id

Return type:

int

sample(n_samples=10, min_wait=0.1, max_attempts=1000, **kwargs)[source]

Sample repositories by trying random IDs.

Parameters:

  • n_samples (int) – Number of valid repositories to collect

  • min_wait (float) – Minimum wait time between API requests

  • max_attempts (int) – Maximum number of IDs to try

  • **kwargs (Any) – Additional filters to apply (filtering happens during collection)

Returns:

List of repository data

Return type:

list[dict[str, Any]]

Advantages

  • Truly random sampling across all public repositories

  • Simple and straightforward approach

  • Good for unbiased statistical sampling

Disadvantages

  • Low hit rate due to many invalid IDs (private/deleted repos)

  • Any filtering must be done after sampling

  • Limited by GitHub API rate limits

Usage Example

from reporoulette import IDSampler

# Direct usage
sampler = IDSampler(token="your_github_token")
repos = sampler.sample(n_samples=10)

# Using convenience function
from reporoulette import sample
results = sample(method='id', n_samples=10)