instructor-examples 0.1.0__py3-none-any.whl

instructor_examples/__init__.py

@@ -0,0 +1 @@
+"""Top-level package for Instructor Examples."""

instructor_examples/__main__.py

@@ -0,0 +1,4 @@
+from .cli import app
+
+if __name__ == "__main__":
+    app()

instructor_examples/cli.py

@@ -0,0 +1,35 @@
+"""Console script for instructor_examples."""
+
+import typer
+from rich.console import Console
+
+from instructor_examples import utils
+
+app = typer.Typer()
+console = Console()
+
+
+@app.command()
+def main(
+    remote_repo_folder: str = typer.Argument(..., help="Input remote_repo_folder path."),
+    out_folder: str = typer.Option(None, help="Optional output folder."),
+    repo: str = typer.Option(None, help="Optional repo path."),
+) -> None:
+    """Console script for instructor_examples."""
+    console.print(f"Input remote_repo_folder: {remote_repo_folder}")
+
+    if out_folder:
+        console.print(f"Output folder: {out_folder}")
+    else:
+        console.print("No output folder specified. Using current folder.")
+
+    utils.run(
+        remote_repo_folder=remote_repo_folder,
+        out_folder=out_folder,
+        repo=repo,
+        console=console,
+    )
+
+
+if __name__ == "__main__":
+    app()

instructor_examples/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561

instructor_examples/utils.py

@@ -0,0 +1,164 @@
+import json
+import os
+from urllib.parse import urlparse
+
+import requests
+from rich.console import Console
+
+
+class InstructorExamplesCopier:
+    def __init__(
+        self,
+        remote_repo_folder: str,
+        out_folder: str | None = None,
+        repo: str | None = None,
+        console: Console | None = None,
+    ) -> None:
+        # clean the remote_repo_folder to remove any non-ASCII characters that might cause issues.
+        self.remote_repo_folder = self.clean_remote_repo_folder(remote_repo_folder)
+
+        if out_folder:
+            print(f"Output folder specified: {out_folder}")
+        else:
+            out_folder = "."
+        # get the repository from settings or by the repo command.
+        self.out_folder = out_folder
+        if self.out_folder is None:
+            self.out_folder = os.getcwd()
+        self.repo = repo
+
+        if repo:
+            print(f"Repo specified: {repo}")
+        else:
+            self.settings_file = self.find_settings_file(out_folder)
+            if self.settings_file:
+                print(f"Found settings file at: {self.settings_file}, parsing...")
+                self.settings = self.parse_settings()
+                self.repo = self.settings.get("repo")
+
+                print(repo)
+            else:
+                print(
+                    "No settings file found. Please specify the --repo option or ensure "
+                    "instructor_examples_settings.json file is in the folder tree."
+                )
+
+        # Initialize repo_owner and repo_name to None. They will be set if the repo URL is valid and can be parsed.
+        self.repo_owner = None
+        self.repo_name = None
+        self.parse_repo_url()
+
+    def clean_remote_repo_folder(self, remote_repo_folder: str) -> str:
+        cleaned_remote_repo_folder = "".join(c for c in remote_repo_folder if ord(c) < 128)
+
+        return cleaned_remote_repo_folder
+
+    def parse_repo_url(self) -> None:
+        """
+        Parse the repository URL to extract the owner and repository name.
+        This is a placeholder implementation. You can replace it with actual parsing logic.
+        """
+        if self.repo:
+            # this is for github only.
+            path = urlparse(self.repo).path.strip("/")
+            owner, repo = path.split("/")[:2]
+            self.repo_owner = owner
+            self.repo_name = repo
+        return None
+
+    def copy_repo_contents(
+        self,
+        repo_folder: str | None = None,
+        folder: str | None = None,
+        branch: str | None = None,
+    ) -> None:
+        """
+        Recursively copy all files and folders from the GitHub repo to the output folder.
+        """
+        if repo_folder is None:
+            repo_folder = self.remote_repo_folder
+        if folder is None:
+            folder = self.out_folder + "/" + repo_folder
+        if not os.path.exists(folder):
+            os.makedirs(folder, exist_ok=True)
+
+        api = f"https://api.github.com/repos/{self.repo_owner}/{self.repo_name}/contents/{repo_folder}"
+        if branch:
+            api += f"?ref={branch}"
+
+        print(f"Fetching: {api}")
+        r = requests.get(api)
+        r.raise_for_status()
+        contents = r.json()
+        # loop through the contents and download files or recurse into directories
+        print("Downloading Folder:", repo_folder)
+        for item in contents:
+            if item["type"] == "file":
+                file_url = item["download_url"]
+                file_path = os.path.join(folder, item["name"])
+
+                content = requests.get(file_url).content
+                with open(file_path, "wb") as f:
+                    f.write(content)
+            elif item["type"] == "dir":
+                subfolder = os.path.join(folder, item["name"])
+                self.copy_repo_contents(
+                    repo_folder=item["path"],
+                    folder=subfolder,
+                    branch=branch,
+                )
+
+    def parse_settings(self) -> dict:
+        """
+        Parse the settings from the found settings file.
+        Returns a dictionary of settings if the file is found and valid, else returns an empty dictionary.
+        """
+        if not hasattr(self, "settings_file") or not self.settings_file:
+            print("No settings file to parse.")
+            return {}
+        try:
+            with open(self.settings_file) as f:
+                settings = json.load(f)
+                print(f"Parsed settings: {settings}")
+                return settings
+        except Exception as e:
+            print(f"Error parsing settings file: {e}")
+            return {}
+
+    def find_settings_file(self, start_path: str | None = None) -> str | None:
+        """
+        Recursively search up the folder tree for the file instructor_examples_settings.json
+        Returns the path to the file if found, else returns None.
+        """
+        print(
+            "Searching for 'instructor_examples_settings.json' starting from:",
+            start_path or os.getcwd(),
+        )
+        if start_path is None:
+            start_path = os.getcwd()
+        current_dir = os.path.abspath(start_path)
+
+        while True:
+            candidate = os.path.join(current_dir, "instructor_examples_settings.json")
+            if os.path.isfile(candidate):
+                return candidate
+            parent_dir = os.path.dirname(current_dir)
+            if parent_dir == current_dir:
+                # Reached the root directory
+                return None
+            current_dir = parent_dir
+
+
+def run(
+    remote_repo_folder: str,
+    repo: str,
+    console: Console,
+    out_folder: str | None = None,
+) -> None:
+    copier = InstructorExamplesCopier(
+        remote_repo_folder=remote_repo_folder,
+        out_folder=out_folder,
+        repo=repo,
+        console=console,
+    )
+    copier.copy_repo_contents()

instructor_examples-0.1.0.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: instructor_examples
+Version: 0.1.0
+Summary: Copy github examples to your local envri
+Project-URL: bugs, https://github.com/dgmouris/instructor_examples/issues
+Project-URL: changelog, https://github.com/dgmouris/instructor_examples/blob/main/HISTORY.md
+Project-URL: documentation, https://dgmouris.github.io/instructor_examples/
+Project-URL: homepage, https://github.com/dgmouris/instructor_examples
+Author-email: Daniel Mouris <dgmouris@gmail.com>
+Maintainer-email: Daniel Mouris <dgmouris@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: requests>=2.32.5
+Requires-Dist: rich
+Requires-Dist: typer
+Description-Content-Type: text/markdown
+
+# Instructor Examples
+
+![PyPI version](https://img.shields.io/pypi/v/instructor_examples.svg)
+
+Copy github examples to your local environment without needing to clone the entire repository.
+
+* Created by **[Daniel Mouris](https://github.com/dgmouris)**
+  * PyPI: https://pypi.org/user/dgmouris/
+* PyPI package: https://pypi.org/project/instructor_examples/
+* Free software: MIT License
+
+## Features
+
+Copies files and folders from GitHub to a local environment.
+
+## Documentation
+
+Documentation is built with [Zensical](https://zensical.org/) and deployed to GitHub Pages.
+
+* **Live site:** https://dgmouris.github.io/instructor_examples/
+* **Preview locally:** `just docs-serve` (serves at http://localhost:8000)
+* **Build:** `just docs-build`
+
+API documentation is auto-generated from docstrings using [mkdocstrings](https://mkdocstrings.github.io/).
+
+Docs deploy automatically on push to `main` via GitHub Actions. To enable this, go to your repo's Settings > Pages and set the source to **GitHub Actions**.
+
+## Development
+
+To set up for local development:
+
+```bash
+# Clone your fork
+git clone git@github.com:your_username/instructor_examples.git
+cd instructor_examples
+
+# Install in editable mode with live updates
+uv tool install --editable .
+```
+
+This installs the CLI globally but with live updates - any changes you make to the source code are immediately available when you run `instructor_examples`.
+
+Run tests:
+
+```bash
+uv run pytest
+```
+
+Run quality checks (format, lint, type check, test):
+
+```bash
+just qa
+```
+
+## Author
+
+Instructor Examples was created in 2026 by Daniel Mouris.
+
+Built with [Cookiecutter](https://github.com/cookiecutter/cookiecutter) and the [audreyfeldroy/cookiecutter-pypackage](https://github.com/audreyfeldroy/cookiecutter-pypackage) project template.

instructor_examples-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+instructor_examples/__init__.py,sha256=MNlPxziqKTbGxSBc8lKtCKYJWhBGQq1tW2oOQyC54OI,49
+instructor_examples/__main__.py,sha256=Qd-f8z2Q2vpiEP2x6PBFsJrpACWDVxFKQk820MhFmHo,59
+instructor_examples/cli.py,sha256=0VUZDVWST8jJUJaoXdZ--CaHReiAg7yKS01u8wd8GLI,900
+instructor_examples/py.typed,sha256=8PjyZ1aVoQpRVvt71muvuq5qE-jTFZkK-GLHkhdebmc,26
+instructor_examples/utils.py,sha256=pNVsEg3jcQtnEwymKF1f7GLYA62EByLqW52eiZ-HI3g,5836
+instructor_examples-0.1.0.dist-info/METADATA,sha256=j20WDA8EIDSUZtQvpJDBF4UGudKUQ4VMCDKESIkniBo,2519
+instructor_examples-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+instructor_examples-0.1.0.dist-info/entry_points.txt,sha256=4tZyKdROomo2LIPxeU8HBsTKjSIJmZTatE3KaqcZdiI,68
+instructor_examples-0.1.0.dist-info/licenses/LICENSE,sha256=UYMM0dCj9_OYWF9EXqVU-clmaT9n1QWQFYYRl1uGaJI,1071
+instructor_examples-0.1.0.dist-info/RECORD,,

instructor_examples-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

instructor_examples-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+instructor_examples = instructor_examples.cli:app

instructor_examples-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026, Daniel Mouris
+
+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.