| Name | vibe_farm JSON |
| Version |
0.1.4
JSON |
| download |
| home_page | None |
| Summary | A Python project in a dev container. |
| upload_time | 2025-07-08 14:00:46 |
| maintainer | None |
| docs_url | None |
| author | Kris Jordan |
| requires_python | >=3.12 |
| license | MIT License
Copyright (c) 2025 Kris Jordan
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 |
python
development
tools
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Vibe Farm
Vibe Farm lets you write normal Python modules that have missing
implementations. Mark any function with the :func:`vibe_farm.farm` decorator and
raise :class:`vibe_farm.code` inside the body. The compiler reads those `.py`
files and generates corresponding `.vibe.py` modules containing the actual
implementation. At runtime, :func:`farm` hot swaps the definitions with their
generated counterparts if present.
The project is designed to run inside a devcontainer, but the CLI works on any
Python 3.12+ environment.
## Quick Start
Install the package (the OpenAI and Anthropic client libraries are installed as
dependencies) and compile a Python file that uses :func:`farm`:
```bash
pip install vibe-farm
vibe_farm compile examples/hello_world/hello_world.py
```
The resulting `.vibe.py` module will appear alongside the source file.
## Design Decisions
Why `@farm` and `raise code()`? An early decision in the exploration is a desire for a few outcomes in the client code:
1. Make the client script directly executable. By decorating, we can hot swap with an LLM-generated implementation at runtime.
2. By raising an exception that extends `NotImplementedError`, the original scripts will still type check "correctly" in IDEs and with static tools such as `mypy`.
## Project Standards & Contribution Guide
### Getting Started
1. **Fork the repository** and clone your fork
2. **Open in a devcontainer** (recommended for consistent tooling)
3. **Wait for the devcontainer to finish setup** - all dependencies are installed automatically
4. **Create a feature branch**: `git checkout -b feature/your-feature-name`
5. **Make your changes** following the development practices below
### Development Environment
- **Devcontainer Ready**: The project includes a complete devcontainer setup with all tools pre-configured
- **Virtual Environment**: Automatically activated in the terminal (`pytest` command works directly)
- **Pre-configured Tools**: Python 3.12+, Poetry, nox, mypy, black, pytest
### Development Workflow
#### Making Changes
1. **Write tests first** - we maintain 100% test coverage
2. **Format your code**: Code is automatically formatted on save, or run `black .`
3. **Run quality checks locally**:
```bash
nox -s lint # Type checking with mypy + black formatting check
nox -s tests # Run full test suite with coverage
nox # Run all sessions (tests + lint for all Python versions)
```
4. **Commit with conventional commit format**:
```bash
git commit -m "feat: add new feature description"
git commit -m "fix: resolve issue with component"
git commit -m "docs: update API documentation"
```
#### Commit Message Format
We use [Conventional Commits](https://www.conventionalcommits.org/). Valid types:
- `feat:` - New features
- `fix:` - Bug fixes
- `docs:` - Documentation changes
- `style:` - Code style changes (formatting, etc.)
- `refactor:` - Code refactoring
- `perf:` - Performance improvements
- `test:` - Adding or updating tests
- `chore:` - Maintenance tasks
- `ci:` - CI/CD changes
- `build:` - Build system changes
#### Pull Request Process
1. **Push your branch** to your fork
2. **Open a Pull Request** against the `main` branch
3. **PR Title**: Must follow conventional commit format (e.g., "feat: add new compiler feature")
4. **Automated Checks**: The following will run automatically:
- **CI Tests**: Full test suite on Python 3.12
- **Code Quality**: mypy type checking and black formatting validation
- **Security**: Dependency vulnerability scanning
- **Coverage**: Must maintain 100% test coverage
- **PR Validation**: Title and commit message format checking
### Continuous Integration
#### Automated Testing
Every pull request and push to `main` triggers:
- **Multi-Python Testing**: Tests run on Python 3.12
- **Full Test Suite**: All unit and integration tests via nox
- **Code Quality Checks**: mypy type checking and black formatting
- **Security Scanning**: Automated dependency vulnerability checks
- **Coverage Reporting**: Results uploaded to Codecov
#### Required Checks
Before merging, all PRs must pass:
- ✅ Tests pass on both Python versions
- ✅ 100% test coverage maintained
- ✅ No mypy type errors
- ✅ Code formatted with black
- ✅ No security vulnerabilities
- ✅ Conventional commit format
- ✅ Code review approved
### Release Process
#### Automated Releases
Releases are automated via GitHub Actions:
1. **Create a version tag**:
```bash
git tag v1.2.3
git push origin v1.2.3
```
2. **Automatic workflow**:
- Full test suite runs on both Python versions
- Package is built with Poetry
- Automatically published to PyPI
- GitHub Release is created
#### Version Management
- Update version in `pyproject.toml` before tagging
- Follow [Semantic Versioning](https://semver.org/)
- Tag format: `v1.2.3` (with 'v' prefix)
### Maintenance
#### Automated Updates
- **Dependabot**: Automatically creates PRs for dependency updates weekly
- **Scheduled Tests**: Full test suite runs daily to catch integration issues
- **Security Monitoring**: Automated scanning for known vulnerabilities
#### Manual Tasks
- Review and merge Dependabot PRs
- Update Python version support as needed
- Maintain documentation and examples
### Tooling
- **Python 3.12+** (managed by devcontainer)
- **Poetry** for dependency management and packaging
- **pytest** for testing
- **pytest-cov** for coverage
- **mypy** for static type checking
- **black** for code formatting
- **nox** for automation of test and lint tasks
- **ESLint, Node, npm** (available in devcontainer for JS/Node interop if needed)
### Development Practices
- **100% Test Coverage**: All code must be covered by tests
- **Type Safety**: Use modern type hints for all public APIs
- **Code Quality**: Format with black, validate with mypy
- **Documentation**: Document public APIs and complex logic
- **Conventional Commits**: Required for all commits and PR titles
### Local Development Commands
```bash
# Format code (done automatically on save in devcontainer)
black .
# Run type checking and formatting validation
nox -s lint
# Run tests with coverage (must maintain 100%)
nox -s tests
# Run everything (tests + lint for all Python versions)
nox
# Run specific Python version
nox -s tests-3.12
nox -s lint-3.12
```
### Testing Requirements
- **Unit Tests**: Test individual functions and classes
- **Integration Tests**: Test CLI commands and workflows
- **Coverage**: Must maintain 100% - no exceptions
- **Mock External Services**: Use mocks for OpenAI/Anthropic APIs
- **Fast Execution**: Tests should complete quickly for CI
### Code Style
- **Formatting**: Black with default settings (line length 88)
- **Type Hints**: Required for all function signatures
- **Imports**: Organized and minimal
- **Documentation**: Docstrings for public APIs using Google style
### Running Tests & Linting
```bash
black . # Format code
nox -s lint # Type checking and lint
nox -s tests # Run unit tests with coverage
nox # Run all automation sessions
```
### CLI Usage
Vibe Farm provides a small CLI with two main commands:
```bash
vibe_farm compile path/to/file.py # generate a .vibe.py implementation
vibe_farm analyze path/to/module.py # inspect code for vibe placeholders
```
Run `vibe_farm --help` for a full list of options.
### Environment Variables
Vibe Farm automatically loads variables from a `.env` file if present. Set the
following keys for each supported provider:
```bash
# OpenAI
OPENAI_API_KEY=your-openai-key
# Anthropic Claude
ANTHROPIC_API_KEY=your-anthropic-key
```
Keep the `.env` file outside version control (it's ignored by `.gitignore`).
### License
This project is distributed under the [MIT License](LICENSE).
### Publishing
- Update version in `pyproject.toml`
- Build and publish with Poetry:
```bash
poetry build
poetry publish
```
---
For more details, see the code and comments, or open an issue/discussion!
Raw data
{
"_id": null,
"home_page": null,
"name": "vibe_farm",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "python, development, tools",
"author": "Kris Jordan",
"author_email": "kris@example.com",
"download_url": "https://files.pythonhosted.org/packages/5a/e8/c02d868fe3867c71f05337d4d9017274a399b770db723e14603b118785fd/vibe_farm-0.1.4.tar.gz",
"platform": null,
"description": "# Vibe Farm\n\nVibe Farm lets you write normal Python modules that have missing\nimplementations. Mark any function with the :func:`vibe_farm.farm` decorator and\nraise :class:`vibe_farm.code` inside the body. The compiler reads those `.py`\nfiles and generates corresponding `.vibe.py` modules containing the actual\nimplementation. At runtime, :func:`farm` hot swaps the definitions with their\ngenerated counterparts if present.\n\nThe project is designed to run inside a devcontainer, but the CLI works on any\nPython 3.12+ environment.\n\n## Quick Start\n\nInstall the package (the OpenAI and Anthropic client libraries are installed as\ndependencies) and compile a Python file that uses :func:`farm`:\n\n```bash\npip install vibe-farm\nvibe_farm compile examples/hello_world/hello_world.py\n```\n\nThe resulting `.vibe.py` module will appear alongside the source file.\n\n## Design Decisions\n\nWhy `@farm` and `raise code()`? An early decision in the exploration is a desire for a few outcomes in the client code:\n\n1. Make the client script directly executable. By decorating, we can hot swap with an LLM-generated implementation at runtime.\n2. By raising an exception that extends `NotImplementedError`, the original scripts will still type check \"correctly\" in IDEs and with static tools such as `mypy`.\n\n## Project Standards & Contribution Guide\n\n### Getting Started\n1. **Fork the repository** and clone your fork\n2. **Open in a devcontainer** (recommended for consistent tooling)\n3. **Wait for the devcontainer to finish setup** - all dependencies are installed automatically\n4. **Create a feature branch**: `git checkout -b feature/your-feature-name`\n5. **Make your changes** following the development practices below\n\n### Development Environment\n- **Devcontainer Ready**: The project includes a complete devcontainer setup with all tools pre-configured\n- **Virtual Environment**: Automatically activated in the terminal (`pytest` command works directly)\n- **Pre-configured Tools**: Python 3.12+, Poetry, nox, mypy, black, pytest\n\n### Development Workflow\n\n#### Making Changes\n1. **Write tests first** - we maintain 100% test coverage\n2. **Format your code**: Code is automatically formatted on save, or run `black .`\n3. **Run quality checks locally**:\n ```bash\n nox -s lint # Type checking with mypy + black formatting check\n nox -s tests # Run full test suite with coverage\n nox # Run all sessions (tests + lint for all Python versions)\n ```\n4. **Commit with conventional commit format**:\n ```bash\n git commit -m \"feat: add new feature description\"\n git commit -m \"fix: resolve issue with component\"\n git commit -m \"docs: update API documentation\"\n ```\n\n#### Commit Message Format\nWe use [Conventional Commits](https://www.conventionalcommits.org/). Valid types:\n- `feat:` - New features\n- `fix:` - Bug fixes \n- `docs:` - Documentation changes\n- `style:` - Code style changes (formatting, etc.)\n- `refactor:` - Code refactoring\n- `perf:` - Performance improvements\n- `test:` - Adding or updating tests\n- `chore:` - Maintenance tasks\n- `ci:` - CI/CD changes\n- `build:` - Build system changes\n\n#### Pull Request Process\n1. **Push your branch** to your fork\n2. **Open a Pull Request** against the `main` branch\n3. **PR Title**: Must follow conventional commit format (e.g., \"feat: add new compiler feature\")\n4. **Automated Checks**: The following will run automatically:\n - **CI Tests**: Full test suite on Python 3.12\n - **Code Quality**: mypy type checking and black formatting validation\n - **Security**: Dependency vulnerability scanning\n - **Coverage**: Must maintain 100% test coverage\n - **PR Validation**: Title and commit message format checking\n\n### Continuous Integration\n\n#### Automated Testing\nEvery pull request and push to `main` triggers:\n- **Multi-Python Testing**: Tests run on Python 3.12\n- **Full Test Suite**: All unit and integration tests via nox\n- **Code Quality Checks**: mypy type checking and black formatting\n- **Security Scanning**: Automated dependency vulnerability checks\n- **Coverage Reporting**: Results uploaded to Codecov\n\n#### Required Checks\nBefore merging, all PRs must pass:\n- \u2705 Tests pass on both Python versions\n- \u2705 100% test coverage maintained\n- \u2705 No mypy type errors\n- \u2705 Code formatted with black\n- \u2705 No security vulnerabilities\n- \u2705 Conventional commit format\n- \u2705 Code review approved\n\n### Release Process\n\n#### Automated Releases\nReleases are automated via GitHub Actions:\n\n1. **Create a version tag**:\n ```bash\n git tag v1.2.3\n git push origin v1.2.3\n ```\n\n2. **Automatic workflow**:\n - Full test suite runs on both Python versions\n - Package is built with Poetry\n - Automatically published to PyPI\n - GitHub Release is created\n\n#### Version Management\n- Update version in `pyproject.toml` before tagging\n- Follow [Semantic Versioning](https://semver.org/)\n- Tag format: `v1.2.3` (with 'v' prefix)\n\n### Maintenance\n\n#### Automated Updates\n- **Dependabot**: Automatically creates PRs for dependency updates weekly\n- **Scheduled Tests**: Full test suite runs daily to catch integration issues\n- **Security Monitoring**: Automated scanning for known vulnerabilities\n\n#### Manual Tasks\n- Review and merge Dependabot PRs\n- Update Python version support as needed\n- Maintain documentation and examples\n\n### Tooling\n- **Python 3.12+** (managed by devcontainer)\n- **Poetry** for dependency management and packaging\n- **pytest** for testing\n- **pytest-cov** for coverage\n- **mypy** for static type checking\n- **black** for code formatting\n- **nox** for automation of test and lint tasks\n- **ESLint, Node, npm** (available in devcontainer for JS/Node interop if needed)\n\n### Development Practices\n- **100% Test Coverage**: All code must be covered by tests\n- **Type Safety**: Use modern type hints for all public APIs\n- **Code Quality**: Format with black, validate with mypy\n- **Documentation**: Document public APIs and complex logic\n- **Conventional Commits**: Required for all commits and PR titles\n\n### Local Development Commands\n```bash\n# Format code (done automatically on save in devcontainer)\nblack .\n\n# Run type checking and formatting validation\nnox -s lint\n\n# Run tests with coverage (must maintain 100%)\nnox -s tests\n\n# Run everything (tests + lint for all Python versions)\nnox\n\n# Run specific Python version\nnox -s tests-3.12\nnox -s lint-3.12\n```\n\n### Testing Requirements\n- **Unit Tests**: Test individual functions and classes\n- **Integration Tests**: Test CLI commands and workflows \n- **Coverage**: Must maintain 100% - no exceptions\n- **Mock External Services**: Use mocks for OpenAI/Anthropic APIs\n- **Fast Execution**: Tests should complete quickly for CI\n\n### Code Style\n- **Formatting**: Black with default settings (line length 88)\n- **Type Hints**: Required for all function signatures\n- **Imports**: Organized and minimal\n- **Documentation**: Docstrings for public APIs using Google style\n\n### Running Tests & Linting\n```bash\nblack . # Format code\nnox -s lint # Type checking and lint\nnox -s tests # Run unit tests with coverage\nnox # Run all automation sessions\n```\n\n### CLI Usage\n\nVibe Farm provides a small CLI with two main commands:\n\n```bash\nvibe_farm compile path/to/file.py # generate a .vibe.py implementation\nvibe_farm analyze path/to/module.py # inspect code for vibe placeholders\n```\n\nRun `vibe_farm --help` for a full list of options.\n\n### Environment Variables\n\nVibe Farm automatically loads variables from a `.env` file if present. Set the\nfollowing keys for each supported provider:\n\n```bash\n# OpenAI\nOPENAI_API_KEY=your-openai-key\n# Anthropic Claude\nANTHROPIC_API_KEY=your-anthropic-key\n```\n\nKeep the `.env` file outside version control (it's ignored by `.gitignore`).\n\n### License\n\nThis project is distributed under the [MIT License](LICENSE).\n\n### Publishing\n- Update version in `pyproject.toml`\n- Build and publish with Poetry:\n ```bash\n poetry build\n poetry publish\n ```\n\n---\nFor more details, see the code and comments, or open an issue/discussion!\n",
"bugtrack_url": null,
"license": "MIT License\n\nCopyright (c) 2025 Kris Jordan\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n",
"summary": "A Python project in a dev container.",
"version": "0.1.4",
"project_urls": null,
"split_keywords": [
"python",
" development",
" tools"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bcc32365d7b2b327ba1e62c02bb856817c0587367875cb25da45ccef661bae05",
"md5": "7dfc42472f4a9f20e57c3dfc9a982cbe",
"sha256": "0c7ef7f7478cf76f9c40f97a83e019b3e3f3862dbc5ef3786f05596307f08b38"
},
"downloads": -1,
"filename": "vibe_farm-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7dfc42472f4a9f20e57c3dfc9a982cbe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 28594,
"upload_time": "2025-07-08T14:00:45",
"upload_time_iso_8601": "2025-07-08T14:00:45.784626Z",
"url": "https://files.pythonhosted.org/packages/bc/c3/2365d7b2b327ba1e62c02bb856817c0587367875cb25da45ccef661bae05/vibe_farm-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5ae8c02d868fe3867c71f05337d4d9017274a399b770db723e14603b118785fd",
"md5": "feaded826ef354b8586d0e0ed3ed3b40",
"sha256": "f5d4a247a0eb88732839c0bb5b6630041537b025a119d2f9ef6c530487202034"
},
"downloads": -1,
"filename": "vibe_farm-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "feaded826ef354b8586d0e0ed3ed3b40",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 22776,
"upload_time": "2025-07-08T14:00:46",
"upload_time_iso_8601": "2025-07-08T14:00:46.578304Z",
"url": "https://files.pythonhosted.org/packages/5a/e8/c02d868fe3867c71f05337d4d9017274a399b770db723e14603b118785fd/vibe_farm-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 14:00:46",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "vibe_farm"
}
