| Name | project-scriber JSON |
| Version |
1.0.1
JSON |
| download |
| home_page | None |
| Summary | An intelligent tool to map, analyze, and compile project source code for LLM context. |
| upload_time | 2025-08-31 10:43:50 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License Copyright (c) 2025 SunneV (Wojciech Mariusz Cichoń) 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. |
| keywords |
code-analysis
context-builder
developer-tools
llm
source-code
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<p align="center">
<img src="https://raw.githubusercontent.com/SunneV/ProjectScriber/main/assets/scriber_logo.svg" alt="ProjectScriber Logo" width="300">
<br>
<img src="https://raw.githubusercontent.com/SunneV/ProjectScriber/main/assets/scriber_name.svg" alt="ProjectScriber Name" width="250">
</p>
<p align="center">
<a href="https://github.com/SunneV/ProjectScriber/releases"><img src="https://img.shields.io/github/v/release/SunneV/ProjectScriber?style=flat&label=latest%20version" alt="Latest Version"></a>
<a href="https://pypi.org/project/project-scriber/"><img src="https://img.shields.io/pypi/v/project-scriber?style=flat" alt="PyPI Version"></a>
</p>
A command-line tool to intelligently map and compile your project's source code into a single, context-optimized text
file for Large Language Models (LLMs).
---
## Why ProjectScriber?
When working with LLMs, providing the full context of a codebase is crucial for getting accurate analysis,
documentation, or refactoring suggestions. Manually copying and pasting files is tedious and error-prone. *
*ProjectScriber** automates this process. It scans your project, respects `.gitignore` rules, applies custom filters,
and bundles all relevant code into a clean, readable format perfect for any AI model.
## Key Features
* **🌳 Smart Project Mapping:** Generates a clear and intuitive tree view of your project's structure.
* **⚙️ Intelligent Filtering:** Automatically respects `.gitignore` rules and supports custom `include` and `exclude`
patterns for fine-grained control.
* **📊 In-depth Code Analysis:** Provides a summary with total file size, estimated token count (using `cl100k_base`),
and a language breakdown.
* **✨ Interactive Setup:** A simple `scriber init` command walks you through creating a configuration file tailored to
your project.
* **📋 Clipboard Integration:** Use the `--copy` flag to automatically copy the entire output to your clipboard.
* **🔧 Flexible Configuration:** Manage settings in a `pyproject.toml` or a project-specific `.scriber.json` file.
---
## Getting Started
Install the package directly from the [Python Package Index (PyPI)](https://pypi.org/project/project-scriber/).
```shell
pip install project-scriber
````
-----
## Usage
#### 1\. Basic Scan
Run `scriber` in your project's root directory. It will generate a `scriber_output.txt` file.
```shell
scriber
```
To target a different directory:
```shell
scriber /path/to/your/project
```
#### 2\. First-Time Configuration
For a new project, run the interactive `init` command to create a `.scriber.json` configuration file.
```shell
scriber init
```
#### 3\. Advanced Example
Scan another project, specify a custom output file, and copy the result to the clipboard in one command.
```shell
scriber ../my-other-project --output custom_map.txt --copy
```
-----
## Commands and Options
| Command/Option | Alias | Description |
|:----------------------|:-----:|:-----------------------------------------------------------------------------|
| `scriber [path]` | | Targets a specific directory. Defaults to the current working directory. |
| `init` | | Starts the interactive process to create a configuration file. |
| `--help` | `-h` | Displays the help message. |
| `--version` | `-v` | Displays the current version of ProjectScriber. |
| `--output [filename]` | `-o` | Specifies a custom name for the output file. |
| `--copy` | `-c` | Copies the final output directly to the clipboard. |
| `--tree-only` | | Generates only the folder structure map, excluding all file contents. |
| `--config [path]` | | Specifies a path to a custom `.json` or `pyproject.toml` configuration file. |
-----
## Configuration
ProjectScriber uses the following order of precedence for loading configurations:
1. **`--config [path]` flag**: Highest priority. If you provide a path to a `.json` or `pyproject.toml` file, its
settings will be used.
2. **`.scriber.json`**: If no `--config` flag is used, Scriber looks for a `.scriber.json` file in the project's root.
This file's settings will override any found in `pyproject.toml`.
3. **`pyproject.toml`**: If neither of the above is found, it looks for a `[tool.scriber]` section in a `pyproject.toml`
file in the project's root.
4. **Default Config**: If no configuration is found, `scriber` will create a default `.scriber.json` on its first run in
a directory.
**Example `.scriber.json`:**
```json
{
"use_gitignore": true,
"exclude": [
"__pycache__",
"node_modules",
"*.log"
],
"include": [
"*.py",
"*.js"
]
}
```
**Example `pyproject.toml`:**
```toml
[tool.scriber]
use_gitignore = true
exclude = [
"__pycache__",
"node_modules",
"*.log"
]
include = [
"*.py",
"*.js"
]
```
-----
## For Developers
### Prerequisites
* Python 3.10 or higher.
### Development Installation
Clone the repository and install it in editable mode with all development dependencies.
```shell
git clone [https://github.com/SunneV/ProjectScriber.git](https://github.com/SunneV/ProjectScriber.git)
cd ProjectScriber
pip install -e .[dev]
```
### Running Tests
Run the test suite using `pytest`.
```shell
pytest
```
-----
## Contributing
Contributions are welcome\! If you have a suggestion or find a bug, please open an issue to discuss it.
Raw data
{
"_id": null,
"home_page": null,
"name": "project-scriber",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "code-analysis, context-builder, developer-tools, llm, source-code",
"author": null,
"author_email": "\"SunneV (Wojciech Mariusz Cicho\u0144)\" <wojciech.m.cichon@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/85/3d/016ce8ae8ba058f0e9a5c44b0cb5e1df69f7d46c90d52c7f40a672a34754/project_scriber-1.0.1.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/SunneV/ProjectScriber/main/assets/scriber_logo.svg\" alt=\"ProjectScriber Logo\" width=\"300\">\n <br>\n <img src=\"https://raw.githubusercontent.com/SunneV/ProjectScriber/main/assets/scriber_name.svg\" alt=\"ProjectScriber Name\" width=\"250\">\n</p>\n<p align=\"center\">\n <a href=\"https://github.com/SunneV/ProjectScriber/releases\"><img src=\"https://img.shields.io/github/v/release/SunneV/ProjectScriber?style=flat&label=latest%20version\" alt=\"Latest Version\"></a>\n <a href=\"https://pypi.org/project/project-scriber/\"><img src=\"https://img.shields.io/pypi/v/project-scriber?style=flat\" alt=\"PyPI Version\"></a>\n</p>\n\nA command-line tool to intelligently map and compile your project's source code into a single, context-optimized text\nfile for Large Language Models (LLMs).\n\n---\n\n## Why ProjectScriber?\n\nWhen working with LLMs, providing the full context of a codebase is crucial for getting accurate analysis,\ndocumentation, or refactoring suggestions. Manually copying and pasting files is tedious and error-prone. *\n*ProjectScriber** automates this process. It scans your project, respects `.gitignore` rules, applies custom filters,\nand bundles all relevant code into a clean, readable format perfect for any AI model.\n\n## Key Features\n\n* **\ud83c\udf33 Smart Project Mapping:** Generates a clear and intuitive tree view of your project's structure.\n* **\u2699\ufe0f Intelligent Filtering:** Automatically respects `.gitignore` rules and supports custom `include` and `exclude`\n patterns for fine-grained control.\n* **\ud83d\udcca In-depth Code Analysis:** Provides a summary with total file size, estimated token count (using `cl100k_base`),\n and a language breakdown.\n* **\u2728 Interactive Setup:** A simple `scriber init` command walks you through creating a configuration file tailored to\n your project.\n* **\ud83d\udccb Clipboard Integration:** Use the `--copy` flag to automatically copy the entire output to your clipboard.\n* **\ud83d\udd27 Flexible Configuration:** Manage settings in a `pyproject.toml` or a project-specific `.scriber.json` file.\n\n---\n\n## Getting Started\n\nInstall the package directly from the [Python Package Index (PyPI)](https://pypi.org/project/project-scriber/).\n\n```shell\npip install project-scriber\n````\n\n-----\n\n## Usage\n\n#### 1\\. Basic Scan\n\nRun `scriber` in your project's root directory. It will generate a `scriber_output.txt` file.\n\n```shell\nscriber\n```\n\nTo target a different directory:\n\n```shell\nscriber /path/to/your/project\n```\n\n#### 2\\. First-Time Configuration\n\nFor a new project, run the interactive `init` command to create a `.scriber.json` configuration file.\n\n```shell\nscriber init\n```\n\n#### 3\\. Advanced Example\n\nScan another project, specify a custom output file, and copy the result to the clipboard in one command.\n\n```shell\nscriber ../my-other-project --output custom_map.txt --copy\n```\n\n-----\n\n## Commands and Options\n\n| Command/Option | Alias | Description |\n|:----------------------|:-----:|:-----------------------------------------------------------------------------|\n| `scriber [path]` | | Targets a specific directory. Defaults to the current working directory. |\n| `init` | | Starts the interactive process to create a configuration file. |\n| `--help` | `-h` | Displays the help message. |\n| `--version` | `-v` | Displays the current version of ProjectScriber. |\n| `--output [filename]` | `-o` | Specifies a custom name for the output file. |\n| `--copy` | `-c` | Copies the final output directly to the clipboard. |\n| `--tree-only` | | Generates only the folder structure map, excluding all file contents. |\n| `--config [path]` | | Specifies a path to a custom `.json` or `pyproject.toml` configuration file. |\n\n-----\n\n## Configuration\n\nProjectScriber uses the following order of precedence for loading configurations:\n\n1. **`--config [path]` flag**: Highest priority. If you provide a path to a `.json` or `pyproject.toml` file, its\n settings will be used.\n2. **`.scriber.json`**: If no `--config` flag is used, Scriber looks for a `.scriber.json` file in the project's root.\n This file's settings will override any found in `pyproject.toml`.\n3. **`pyproject.toml`**: If neither of the above is found, it looks for a `[tool.scriber]` section in a `pyproject.toml`\n file in the project's root.\n4. **Default Config**: If no configuration is found, `scriber` will create a default `.scriber.json` on its first run in\n a directory.\n\n**Example `.scriber.json`:**\n\n```json\n{\n \"use_gitignore\": true,\n \"exclude\": [\n \"__pycache__\",\n \"node_modules\",\n \"*.log\"\n ],\n \"include\": [\n \"*.py\",\n \"*.js\"\n ]\n}\n```\n\n**Example `pyproject.toml`:**\n\n```toml\n[tool.scriber]\nuse_gitignore = true\nexclude = [\n \"__pycache__\",\n \"node_modules\",\n \"*.log\"\n]\ninclude = [\n \"*.py\",\n \"*.js\"\n]\n```\n\n-----\n\n## For Developers\n\n### Prerequisites\n\n* Python 3.10 or higher.\n\n### Development Installation\n\nClone the repository and install it in editable mode with all development dependencies.\n\n```shell\ngit clone [https://github.com/SunneV/ProjectScriber.git](https://github.com/SunneV/ProjectScriber.git)\ncd ProjectScriber\npip install -e .[dev]\n```\n\n### Running Tests\n\nRun the test suite using `pytest`.\n\n```shell\npytest\n```\n\n-----\n\n## Contributing\n\nContributions are welcome\\! If you have a suggestion or find a bug, please open an issue to discuss it.\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2025 SunneV (Wojciech Mariusz Cicho\u0144) 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.",
"summary": "An intelligent tool to map, analyze, and compile project source code for LLM context.",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/SunneV/ProjectScriber",
"Issues": "https://github.com/SunneV/ProjectScriber/issues"
},
"split_keywords": [
"code-analysis",
" context-builder",
" developer-tools",
" llm",
" source-code"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d4c81a3e8e2f859b9ebce17ca21fcba927d71992ccf26a34cd7f30403ce63102",
"md5": "083a76a13393ec7cbc266ac753bd8145",
"sha256": "1121ebf5e6d130fcd4c6eb5f4590d0bf77b3e9125461e2b343d537a3299229d6"
},
"downloads": -1,
"filename": "project_scriber-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "083a76a13393ec7cbc266ac753bd8145",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 12835,
"upload_time": "2025-08-31T10:43:50",
"upload_time_iso_8601": "2025-08-31T10:43:50.163286Z",
"url": "https://files.pythonhosted.org/packages/d4/c8/1a3e8e2f859b9ebce17ca21fcba927d71992ccf26a34cd7f30403ce63102/project_scriber-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "853d016ce8ae8ba058f0e9a5c44b0cb5e1df69f7d46c90d52c7f40a672a34754",
"md5": "6f7dc4574f06bb2ee2c04f371bcc7b7f",
"sha256": "b512b64bc7df539269fc3354514d6ddc5fb1ca264ab4e00e0236f0845d69579e"
},
"downloads": -1,
"filename": "project_scriber-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "6f7dc4574f06bb2ee2c04f371bcc7b7f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 25854,
"upload_time": "2025-08-31T10:43:50",
"upload_time_iso_8601": "2025-08-31T10:43:50.934803Z",
"url": "https://files.pythonhosted.org/packages/85/3d/016ce8ae8ba058f0e9a5c44b0cb5e1df69f7d46c90d52c7f40a672a34754/project_scriber-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-31 10:43:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SunneV",
"github_project": "ProjectScriber",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "project-scriber"
}
