Metadata-Version: 2.4
Name: python-project-doctor-cli
Version: 0.1.0
Summary: A beginner-friendly CLI that checks whether a directory looks like a Python project and suggests what to do next.
Author: x1958075990h-pixel
License: MIT License
        
        Copyright (c) 2026 x1958075990h-pixel
        
        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.
        
Project-URL: Homepage, https://github.com/x1958075990h-pixel/pyenv-doctor
Project-URL: Repository, https://github.com/x1958075990h-pixel/pyenv-doctor
Project-URL: Issues, https://github.com/x1958075990h-pixel/issues
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# pyenv-doctor

`pyenv-doctor` is a minimal Python command-line tool for beginners.

It scans a directory, checks whether it looks like a Python project, and tells you whether the current Python interpreter is running inside a virtual environment.

## What It Checks

This MVP checks for these common Python project files:

- `requirements.txt`
- `pyproject.toml`
- `setup.py`
- `setup.cfg`
- `Pipfile`
- `poetry.lock`
- `uv.lock`
- `environment.yml`
- `.python-version`

If at least one of them exists, the tool prints:

`Conclusion: this looks like a Python project`

It also checks whether the current Python is running in a virtual environment.
After the scan, it prints a short list of beginner-friendly suggestions based on the result.

Supported common cases:

- `venv`
- `virtualenv`
- `Conda`

## Why Virtual Environments Are Useful

Virtual environments help keep project dependencies isolated.
This makes it easier to avoid version conflicts between different Python projects on the same machine.

## Project Structure

```text
pyenv-doctor/
|-- .gitignore
|-- .github/
|   |-- workflows/
|   |   |-- ci.yml
|   |   `-- publish.yml
|-- pyproject.toml
|-- README.md
|-- requirements.txt
|-- LICENSE
|-- main.py
`-- tests/
    `-- test_main.py
```

## Installation

### 1. Make sure Python 3.11 or newer is available

```powershell
python --version
```

### 2. Install from PyPI

The PyPI package name is:

```text
python-project-doctor-cli
```

Install it with:

```powershell
python -m pip install python-project-doctor-cli
```

The installed command name is still:

```powershell
pyenv-doctor
```

### 3. Install locally from source

Clone the repository, enter the project directory, and install it locally:

```powershell
python -m pip install .
```

For local development, you can also use editable install:

```powershell
python -m pip install -e .
```

## Run

Run the installed CLI command:

```powershell
pyenv-doctor
pyenv-doctor .
pyenv-doctor C:\my-project
pyenv-doctor . --json
```

Run the tool from source:

```powershell
python main.py
python main.py C:\my-project
python main.py C:\my-project --json
```

### Windows note for virtual environment detection

If you want to verify virtual environment detection on Windows, activate the virtual environment first and then run:

```powershell
python main.py
```

This is recommended because `py -3.14 main.py` may use the system interpreter instead of the currently activated virtual environment.

## Run Tests

Run the test suite with:

```powershell
python -m unittest discover -s tests -v
```

## Exit Codes

- `0`: the scan completed successfully
- non-zero: the scan failed because the path was invalid or the arguments were invalid

## JSON Output

Use `--json` to get machine-readable output:

```powershell
pyenv-doctor . --json
python main.py . --json
```

The JSON output includes:

- `scanned_directory`
- `found_files`
- `looks_like_python_project`
- `virtual_environment_detected`
- `error`
- `suggestions`

## Example Output

### Example 1: Python project detected, virtual environment detected

```text
Scanned directory: C:\demo\my-project

Project file detection:
- requirements.txt: not found
- pyproject.toml: found
- setup.py: not found
- setup.cfg: not found
- Pipfile: not found
- poetry.lock: found
- uv.lock: not found
- environment.yml: not found
- .python-version: not found

Conclusion: this looks like a Python project
Reason: detected pyproject.toml, poetry.lock

Virtual environment detection:
Virtual environment: detected

Suggestions:
- Open pyproject.toml to check how this project should be installed or run.
- If this project uses Poetry, review pyproject.toml and try poetry install.
```

### Example 2: No project markers, no virtual environment

```text
Scanned directory: C:\demo\empty-folder

Project file detection:
- requirements.txt: not found
- pyproject.toml: not found
- setup.py: not found
- setup.cfg: not found
- Pipfile: not found
- poetry.lock: not found
- uv.lock: not found
- environment.yml: not found
- .python-version: not found

Conclusion: no clear Python project markers were found
Details: common Python project files were not found in this directory.

Virtual environment detection:
Virtual environment: not detected
Recommendation: use venv or Conda for an isolated Python environment

Suggestions:
- Verify that you are scanning the project root directory.
```

### Example 3: Invalid path

```text
Error: path does not exist: C:\does-not-exist

Suggestions:
- Check the path spelling and try again.
```

### Example 4: JSON output

```json
{
  "scanned_directory": "C:\\demo\\my-project",
  "found_files": [
    "Pipfile",
    ".python-version"
  ],
  "looks_like_python_project": true,
  "virtual_environment_detected": false,
  "error": null,
  "suggestions": [
    "Open Pipfile to review the project's dependencies and environment settings.",
    "Check .python-version to see which Python version this project expects."
  ]
}
```

## Publishing

This repository includes a GitHub Actions workflow for trusted publishing to PyPI when a GitHub release is published.

To use it, first add this repository as a trusted publisher in your PyPI project settings.
Then create a GitHub release to trigger the publish workflow.

## Roadmap

- Improve test coverage
- Improve detection rules for different Python workflows

## License

This project is licensed under the [MIT License](LICENSE).
