hackerrank-cli 2026.10.1.1__py3-none-any.whl

hackerrank_cli/__init__.py

@@ -0,0 +1,224 @@
+"""Upload project starter code using the released HackerRank SDK."""
+
+import os
+from importlib.metadata import version
+from io import BytesIO
+from pathlib import Path
+from zipfile import ZIP_DEFLATED, ZipFile, ZipInfo
+
+import click
+import httpx
+import httpx2
+from hackerrank.client import HackerRank
+from hackerrank.exceptions import HackerRankError
+from hackerrank.transports import Transport
+
+from hackerrank_cli._sources import PreparedSource, prepare_source
+
+
+def create_cli(*, transport: Transport | None = None) -> click.Group:
+    """Create the CLI, optionally using a supported SDK transport."""
+
+    @click.group(name="hackerrank")
+    @click.version_option(
+        version=version(distribution_name="hackerrank-cli"),
+        prog_name="hackerrank",
+    )
+    def cli() -> None:
+        """Upload starter files to existing HackerRank project
+        questions.
+        """
+
+    @cli.group()
+    def questions() -> None:
+        """Manage project-question starter files."""
+
+    @click.argument("question_id")
+    @click.option(
+        "--directory",
+        type=click.Path(path_type=Path, readable=False),
+        help="Project directory.",
+    )
+    @click.option(
+        "--file",
+        "source_file",
+        type=click.Path(path_type=Path, readable=False),
+        help="One starter file, uploaded as a single-file project archive.",
+    )
+    @click.option(
+        "--exclude",
+        multiple=True,
+        help="Additional Gitignore pattern at the upload root. Repeatable.",
+    )
+    @click.option(
+        "--dry-run",
+        is_flag=True,
+        help="Validate and list files without credentials or network access.",
+    )
+    @click.option(
+        "--retries",
+        type=click.IntRange(min=0),
+        default=0,
+        show_default=True,
+        help="Retry count delegated to the SDK for this repeatable upload.",
+    )
+    def upload(  # noqa: PLR0913 - Click command options.
+        question_id: str,
+        directory: Path | None,
+        source_file: Path | None,
+        exclude: tuple[str, ...],
+        retries: int,
+        *,
+        dry_run: bool,
+    ) -> None:
+        """Replace project starter files while preserving question
+        metadata.
+        """
+        _upload(
+            question_id=question_id,
+            directory=directory,
+            source_file=source_file,
+            exclude=exclude,
+            retries=retries,
+            dry_run=dry_run,
+            transport=transport,
+        )
+
+    _ = questions.command()(upload)
+    return cli
+
+
+def _validate_upload(
+    question_id: str,
+    directory: Path | None,
+    source_file: Path | None,
+    exclude: tuple[str, ...],
+) -> None:
+    """Validate command combinations and the question identifier."""
+    if (directory is None) == (source_file is None):
+        msg = "Provide exactly one of --directory or --file."
+        raise click.UsageError(message=msg)
+    if (
+        not question_id.isascii()
+        or not question_id.isdecimal()
+        or int(question_id) < 1
+    ):
+        msg = "QUESTION_ID must be a positive decimal integer."
+        raise click.BadParameter(message=msg, param_hint="QUESTION_ID")
+    if len(exclude) > 0 and directory is None:
+        msg = "--exclude requires --directory."
+        raise click.UsageError(message=msg)
+
+
+def _api_key() -> str:
+    """Read a nonempty API token without printing its value."""
+    api_key = os.environ.get(key="HACKERRANK_API_TOKEN")
+    if api_key is None or api_key.strip() == "":
+        msg = (
+            "HACKERRANK_API_TOKEN is missing or empty. "
+            "Set it in the environment."
+        )
+        raise click.ClickException(message=msg)
+    return api_key
+
+
+def _project_zip(source: PreparedSource) -> bytes:
+    """Package prepared starter files for the released SDK's ZIP API."""
+    with BytesIO() as buffer:
+        with ZipFile(
+            file=buffer, mode="w", compression=ZIP_DEFLATED
+        ) as archive:
+            if source.directory is None:
+                info = ZipInfo(filename=Path(source.files[0]).name)
+                info.external_attr = source.file_mode << 16
+                archive.writestr(
+                    zinfo_or_arcname=info,
+                    data=source.contents,
+                    compress_type=ZIP_DEFLATED,
+                )
+            else:
+                for name in source.files:
+                    archive.write(
+                        filename=source.directory / name, arcname=name
+                    )
+        return buffer.getvalue()
+
+
+def _send_upload(
+    question_id: str,
+    archive: bytes,
+    retries: int,
+    transport: Transport | None,
+) -> None:
+    """Delegate communication and retries to the SDK; report safe
+    errors.
+    """
+    api_key = _api_key()
+    try:
+        with HackerRank(
+            api_key=api_key, transport=transport, retries=retries
+        ) as client:
+            _ = client.questions.upload_project_zip(
+                question_id=question_id, file=archive
+            )
+    except HackerRankError as error:
+        # Response bodies can contain secrets; only report the status.
+        msg = f"HackerRank rejected the upload (HTTP {error.status_code})."
+        raise click.ClickException(message=msg) from None
+    except (httpx.TransportError, httpx2.TransportError):
+        msg = "Could not reach HackerRank. Check your network connection."
+        raise click.ClickException(message=msg) from None
+    except (ValueError, TypeError):
+        msg = (
+            "HackerRank returned an invalid response. The upload may have "
+            "succeeded; check the question before trying again."
+        )
+        raise click.ClickException(message=msg) from None
+
+
+def _upload(  # noqa: PLR0913 - Click options plus the SDK transport boundary.
+    question_id: str,
+    directory: Path | None,
+    source_file: Path | None,
+    exclude: tuple[str, ...],
+    retries: int,
+    *,
+    dry_run: bool,
+    transport: Transport | None,
+) -> None:
+    """Prepare every byte before credentials or a network mutation."""
+    _validate_upload(
+        question_id=question_id,
+        directory=directory,
+        source_file=source_file,
+        exclude=exclude,
+    )
+    try:
+        with prepare_source(
+            directory=directory, file=source_file, excludes=exclude
+        ) as source:
+            archive = _project_zip(source=source)
+            target = f"HackerRank project question {question_id}"
+            if dry_run:
+                click.echo(message=f"Would update {target}")
+                for path in source.files:
+                    click.echo(message=f"  {path}")
+                return
+            _send_upload(
+                question_id=question_id,
+                archive=archive,
+                retries=retries,
+                transport=transport,
+            )
+            click.echo(message=f"Updated {target}")
+    except UnicodeError:
+        msg = ".gitignore files must be valid UTF-8."
+        raise click.ClickException(message=msg) from None
+    except OSError as error:
+        msg = f"Could not prepare upload files ({type(error).__name__})."
+        raise click.ClickException(message=msg) from None
+    except ValueError as error:
+        raise click.ClickException(message=str(object=error)) from None
+
+
+main: click.Group = create_cli()

hackerrank_cli/__main__.py

@@ -0,0 +1,5 @@
+"""Run the CLI with ``python -m hackerrank_cli``."""
+
+from hackerrank_cli import main
+
+main()

hackerrank_cli/_sources.py

@@ -0,0 +1,182 @@
+"""Prepare local sources before handing them to the SDK."""
+
+import stat
+from collections.abc import Generator, Iterator, Sequence
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from shutil import copyfile, copymode
+from tempfile import TemporaryDirectory
+
+from pathspec import GitIgnoreSpec
+
+
+def validate_path(path: Path) -> None:
+    """Reject symlinks in the path and its ancestors before resolving
+    it.
+    """
+    for component in (path, *path.parents):
+        if component.name.casefold() == ".git":
+            msg = f"Git metadata cannot be uploaded: {component}"
+            raise ValueError(msg)
+        if component.is_symlink():
+            msg = f"Symbolic links are not supported: {component}"
+            raise ValueError(msg)
+
+
+def _rules(directory: Path) -> tuple[tuple[Path, GitIgnoreSpec], ...]:
+    """Read one directory's ignore rules without following symlinks."""
+    ignore_file = directory / ".gitignore"
+    if ignore_file.is_symlink():
+        validate_path(path=ignore_file)
+    if ignore_file.is_file():
+        return (
+            (
+                directory,
+                GitIgnoreSpec.from_lines(
+                    lines=ignore_file.read_text(encoding="utf-8").splitlines(),
+                ),
+            ),
+        )
+    return ()
+
+
+def _inherited_rules(
+    directory: Path,
+) -> tuple[tuple[Path, GitIgnoreSpec], ...] | None:
+    """Inherit rules from the nearest Git root, or start at the source."""
+    for candidate in (directory, *directory.parents):
+        if (candidate / ".git").exists():
+            bases = [directory]
+            while bases[-1] != candidate:
+                bases.append(bases[-1].parent)
+            rules: list[tuple[Path, GitIgnoreSpec]] = []
+            for base in reversed(bases):
+                if _is_ignored(path=base, rules=rules, suffix="/"):
+                    return None
+                rules.extend(_rules(directory=base))
+            return tuple(rules)
+    return _rules(directory=directory)
+
+
+def _is_ignored(
+    path: Path,
+    rules: Sequence[tuple[Path, GitIgnoreSpec]],
+    *,
+    suffix: str,
+) -> bool:
+    """Apply the last matching rule from the deepest matching ignore
+    file.
+    """
+    ignored = False
+    for base, spec in rules:
+        match = spec.check_file(
+            file=path.relative_to(base).as_posix() + suffix
+        )
+        if match.include is not None:
+            ignored = match.include
+    return ignored
+
+
+def require_regular_file(path: Path) -> None:
+    """Reject devices, pipes, and other special files before reading."""
+    if not stat.S_ISREG(path.stat().st_mode):
+        msg = f"Only regular files are supported: {path}"
+        raise ValueError(msg)
+
+
+def selected_files(
+    directory: Path, excludes: tuple[str, ...]
+) -> tuple[Path, ...]:
+    """Select regular files using layered Git ignores and final exclusions."""
+    exclusion_spec = GitIgnoreSpec.from_lines(lines=excludes)
+
+    def walk(
+        parent: Path, rules: tuple[tuple[Path, GitIgnoreSpec], ...]
+    ) -> Iterator[Path]:
+        """Traverse selected directories without following links."""
+        for path in sorted(parent.iterdir()):
+            if path.name.casefold() == ".git":
+                continue
+            is_directory = path.is_dir()
+            suffix = "/" if is_directory else ""
+            relative = path.relative_to(directory).as_posix() + suffix
+            if exclusion_spec.match_file(file=relative):
+                continue
+            if _is_ignored(path=path, rules=rules, suffix=suffix):
+                continue
+            validate_path(path=path)
+            if is_directory:
+                yield from walk(
+                    parent=path, rules=(*rules, *_rules(directory=path))
+                )
+            else:
+                require_regular_file(path=path)
+                yield path.relative_to(directory)
+
+    inherited = _inherited_rules(directory=directory)
+    if inherited is None:
+        return ()
+    return tuple(walk(parent=directory, rules=inherited))
+
+
+@dataclass(frozen=True)
+class PreparedSource:
+    """Validated bytes or an isolated directory for ZIP preparation."""
+
+    contents: bytes
+    directory: Path | None
+    files: tuple[str, ...]
+    file_mode: int
+
+
+@contextmanager
+def prepare_source(
+    *, directory: Path | None, file: Path | None, excludes: tuple[str, ...]
+) -> Generator[PreparedSource]:
+    """Read or stage everything before allowing a network mutation."""
+    if file is not None:
+        validate_path(path=file.absolute())
+        if not file.is_file():
+            msg = f"Not a regular file: {file}"
+            raise ValueError(msg)
+        # Preserve source bytes, including non-UTF-8 files.
+        contents = file.read_bytes()
+        yield PreparedSource(
+            contents=contents,
+            directory=None,
+            files=(str(object=file),),
+            file_mode=file.stat().st_mode,
+        )
+        return
+    if directory is None:
+        msg = "Provide exactly one of --directory or --file."
+        raise ValueError(msg)
+    validate_path(path=directory.absolute())
+    directory = directory.resolve(strict=True)
+    if not directory.is_dir():
+        msg = f"Not a directory: {directory}"
+        raise ValueError(msg)
+    files = selected_files(directory=directory, excludes=excludes)
+    if len(files) == 0:
+        msg = "No files selected for upload."
+        raise ValueError(msg)
+    with TemporaryDirectory(prefix="hackerrank-cli-") as temporary:
+        staged = Path(temporary).resolve() / "project"
+        staged.mkdir()
+        for relative in files:
+            source = directory / relative
+            validate_path(path=source)
+            target = staged / relative
+            target.parent.mkdir(parents=True, exist_ok=True)
+            # Never dereference a symlink introduced after selection.
+            # Validate the copied path before packaging its bytes.
+            _ = copyfile(src=source, dst=target, follow_symlinks=False)
+            validate_path(path=target)
+            copymode(src=source, dst=target, follow_symlinks=False)
+        yield PreparedSource(
+            contents=b"",
+            directory=staged,
+            files=tuple(path.as_posix() for path in files),
+            file_mode=0,
+        )

hackerrank_cli/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '2026.10.1.1'
+__version_tuple__ = version_tuple = (2026, 10, 1, 1)
+
+__commit_id__ = commit_id = None

hackerrank_cli-2026.10.1.1.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: hackerrank-cli
+Version: 2026.10.1.1
+Summary: Upload starter files to existing HackerRank project questions.
+Author-email: Adam Dangoor <adamdangoor@gmail.com>
+License-Expression: MIT
+Project-URL: Documentation, https://adamtheturtle.github.io/hackerrank-cli/
+Project-URL: Issues, https://github.com/adamtheturtle/hackerrank-cli/issues
+Project-URL: Source, https://github.com/adamtheturtle/hackerrank-cli
+Keywords: cli,hackerrank,starter-code
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.13
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: click<8.6,>=8.3
+Requires-Dist: hackerrank>=2026.9.16
+Requires-Dist: httpx>=0.28
+Requires-Dist: httpx2>=2.12
+Requires-Dist: pathspec>=1
+Dynamic: license-file
+
+hackerrank-cli
+==============
+
+Upload starter files to an existing HackerRank for Work project question using
+the ``hackerrank`` Python SDK.
+This independent CLI replaces only the project archive, preserving the
+question's name, problem statement, environment, scoring settings, and other
+metadata.
+
+The initial scope is project questions such as fullstack, frontend, and backend
+projects.
+Language-specific coding-question stubs are outside this CLI's initial scope.
+
+Requires Python 3.13 or later.
+Install from PyPI:
+
+.. code-block:: console
+
+   uv tool install hackerrank-cli
+   hackerrank --help
+   hackerrank --version
+
+You can also install with ``pip install hackerrank-cli``.
+
+Usage
+-----
+
+Use synthetic question ID ``123456`` below in place of your own question ID.
+Exactly one content source is required:
+
+.. code-block:: console
+
+   hackerrank questions upload 123456 --directory ./starter --dry-run
+   hackerrank questions upload 123456 --directory ./starter --exclude '*.zip'
+   hackerrank questions upload 123456 --file ./starter.py
+
+Real uploads read ``HACKERRANK_API_TOKEN`` from the environment.
+Get a key from the HackerRank for Work API tokens page.
+Missing, empty, and whitespace-only keys fail clearly.
+Dry runs need no key and make no network requests.
+
+Exactly one of ``--directory`` or ``--file`` is required.
+Both replace the entire project archive.
+``--file`` creates a one-file project using the source's basename; it does not
+update a language-specific code stub or upload a prebuilt ZIP as the project
+archive.
+
+All file bytes are preserved exactly, including binary files, CRLF, blank
+lines, trailing whitespace, UTF-8 BOMs, and documentation markers.
+Empty single files are valid.
+Neither paths nor IDs are inferred from repository configuration.
+Inputs are fully read, staged, and archived before credentials are read or a
+mutation is issued.
+POSIX executable bits are preserved.
+Errors exit nonzero.
+API response bodies and credentials are never printed.
+The default retry count is zero, matching the released SDK.
+Set ``--retries 3`` to delegate retries and backoff to the SDK for this
+repeatable upload.
+The CLI adds no separate retry loop.
+Each attempt uses the same prepared archive bytes.
+
+Directory selection
+-------------------
+
+* Both Git and non-Git directories work.
+  Paths are relative to the current working directory.
+  A Git worktree's ``.git`` file also identifies its root.
+* In a Git repository, rules are inherited from the nearest Git root down to
+  the upload directory.
+  Outside Git, rules start at the upload directory; unrelated parent
+  ``.gitignore`` files are not used.
+* Each traversed directory adds its own ``.gitignore`` rules.
+  Later matching rules override earlier ones, and deeper files override
+  ancestor rules.
+  Patterns are relative to their owning directory.
+  Directory-only rules and negations follow Gitignore semantics.
+  Excluded directories are pruned, so a child cannot re-include itself unless
+  its parent is re-included first.
+  This also applies to ancestors of an explicitly selected nested upload root.
+* Ignore rules apply to tracked files too.
+  Global Git excludes and ``.git/info/exclude`` are not read.
+  Hidden files, including ``.gitignore``, are uploaded unless excluded.
+* ``.git`` files and directories are always excluded at every depth.
+  Explicit source paths inside Git metadata are rejected, including an upload
+  rooted at a ``.git`` directory.
+  Repeatable ``--exclude PATTERN`` options form a final Gitignore rule layer,
+  relative to the upload root.
+  This layer can exclude files re-included by ``.gitignore``; its own later
+  negations can undo its earlier patterns.
+  It cannot re-include a file excluded by ``.gitignore`` or Git metadata.
+* ZIP files are included by default.
+  Use ``--exclude '*.zip'`` to omit them.
+  Add other exclusions explicitly, such as ``--exclude node_modules/``.
+* Selected symlinks (including directory, broken, and external links) and
+  symlinks in the source path are rejected rather than dereferenced.
+  Ignored links are skipped.
+  Symlinked ``.gitignore`` files are rejected when their rules would be read.
+  Special files are rejected.
+  Empty selections fail.
+  Selected files are copied to a temporary directory without dereferencing
+  links.
+  The CLI packages these prepared files with Python's standard ZIP library.
+  The released SDK handles multipart serialization, authentication, network
+  requests, response decoding, and retries.
+
+Development and distribution
+----------------------------
+
+Development checks, release setup, and build instructions for Docker, Nix, and
+standalone binaries are in ``docs/source/development.rst``.
+The generated CLI reference is in ``docs/source/cli.rst``.
+Prebuilt binaries are available from
+`GitHub Releases <https://github.com/adamtheturtle/hackerrank-cli/releases>`_.
+
+See ``docs/source/migration.rst`` for migrating an existing shell uploader and
+keeping repository-specific snippet preparation outside this CLI.

hackerrank_cli-2026.10.1.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+hackerrank_cli/__init__.py,sha256=-RqNWmLXJEibbEX794M_7Q-gzDRskf0kRZc1y9EQdTA,7293
+hackerrank_cli/__main__.py,sha256=OCJH11M4QDshkTS5Rci0dUfLZr0YFnzK2aI9yrmWARM,94
+hackerrank_cli/_sources.py,sha256=--ATApfmrcLjxNV4CEZjZrVWeolBm7MDoXjB-3-lJcw,6314
+hackerrank_cli/_version.py,sha256=K6nZoD8HmqUbtHmEmxFXtR8SK0DcDTd6MDQMVfC4jZ8,533
+hackerrank_cli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hackerrank_cli-2026.10.1.1.dist-info/licenses/LICENSE,sha256=cnfgEzv8YMudbgPysNfgAdqeOo4zf0y2C3Ctw4RgEE4,1069
+hackerrank_cli-2026.10.1.1.dist-info/METADATA,sha256=TZwDOMuKuOQqYiO1cWGwoRBtnbC4P8590rsxh--8sxM,6016
+hackerrank_cli-2026.10.1.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+hackerrank_cli-2026.10.1.1.dist-info/entry_points.txt,sha256=3nj4emp_aSgrj_m-OUnLyAVsvW3_VPQpZ4gYe8_oMMg,51
+hackerrank_cli-2026.10.1.1.dist-info/top_level.txt,sha256=SE7-lgO007qGO9eJpU0uWdu6Sy7k5kvojWMB1Im9lX0,15
+hackerrank_cli-2026.10.1.1.dist-info/RECORD,,

hackerrank_cli-2026.10.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hackerrank_cli-2026.10.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hackerrank = hackerrank_cli:main

hackerrank_cli-2026.10.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Dangoor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hackerrank_cli-2026.10.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+hackerrank_cli