python-project-doctor-cli 0.1.0__py3-none-any.whl

main.py

@@ -0,0 +1,305 @@
+"""Minimal command-line entry point for pyenv-doctor."""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+
+# These files are the simplest markers for a Python project in this MVP.
+PROJECT_MARKER_FILES = [
+    "requirements.txt",
+    "pyproject.toml",
+    "setup.py",
+    "setup.cfg",
+    "Pipfile",
+    "poetry.lock",
+    "uv.lock",
+    "environment.yml",
+    ".python-version",
+]
+
+
+class JsonAwareArgumentParser(argparse.ArgumentParser):
+    """Argument parser that can return JSON-formatted errors when requested."""
+
+    def __init__(self, *args, **kwargs) -> None:
+        """Create the parser and remember whether JSON mode is requested."""
+        super().__init__(*args, **kwargs)
+        self.json_output = False
+
+    def error(self, message: str) -> None:
+        """Print a JSON error instead of plain text when JSON mode is enabled."""
+        if self.json_output:
+            print_json_result(build_result(error=f"Argument error: {message}"))
+            raise SystemExit(2)
+
+        super().error(message)
+
+
+def build_parser() -> JsonAwareArgumentParser:
+    """Create the command-line argument parser."""
+    parser = JsonAwareArgumentParser(
+        prog="pyenv-doctor",
+        description="Scan a directory and check whether it looks like a Python project.",
+    )
+    # This optional path keeps the CLI simple: no argument means current directory.
+    parser.add_argument(
+        "path",
+        nargs="?",
+        help="Optional directory path to scan. If omitted, the current directory is used.",
+    )
+    # This flag switches the output from human-readable text to structured JSON.
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Print the result as JSON.",
+    )
+    return parser
+
+
+def get_scan_path(path_argument: str | None) -> tuple[Path | None, str | None, str | None]:
+    """Return the scan path, an optional error message, and the displayed path string."""
+    # If no path was provided, keep the original behavior and scan the current directory.
+    if path_argument is None:
+        scan_path = Path.cwd().resolve()
+        return scan_path, None, str(scan_path)
+
+    # Expand user input so paths like `~` work on supported systems.
+    scan_path = Path(path_argument).expanduser()
+
+    # Return a clear error when the path does not exist.
+    if not scan_path.exists():
+        return None, f"Error: path does not exist: {scan_path}", str(scan_path)
+
+    # Return a clear error when the path exists but is not a directory.
+    if not scan_path.is_dir():
+        return None, f"Error: path is not a directory: {scan_path}", str(scan_path)
+
+    # Resolve the final directory so the output shows a clear absolute path.
+    resolved_path = scan_path.resolve()
+    return resolved_path, None, str(resolved_path)
+
+
+def find_marker_files(scan_path: Path) -> list[str]:
+    """Return the project marker files found in the current directory."""
+    found_files: list[str] = []
+
+    # Check each file one by one so the logic stays easy to read.
+    for file_name in PROJECT_MARKER_FILES:
+        if (scan_path / file_name).is_file():
+            found_files.append(file_name)
+
+    return found_files
+
+
+def is_virtual_environment_detected() -> bool:
+    """Return True when the current Python looks like it runs in a virtual environment."""
+    # Conda usually exposes these environment variables when an environment is active.
+    if os.environ.get("CONDA_PREFIX") or os.environ.get("CONDA_DEFAULT_ENV"):
+        return True
+
+    # venv changes sys.prefix while keeping the original value in sys.base_prefix.
+    if getattr(sys, "base_prefix", sys.prefix) != sys.prefix:
+        return True
+
+    # Older virtualenv versions may set sys.real_prefix.
+    if hasattr(sys, "real_prefix"):
+        return True
+
+    return False
+
+
+def build_suggestions(
+    found_files: list[str] | None = None,
+    error: str | None = None,
+    virtual_environment_detected: bool = False,
+) -> list[str]:
+    """Build a short list of beginner-friendly next steps."""
+    detected_files = found_files if found_files is not None else []
+
+    # Error suggestions should stay focused on fixing the immediate problem first.
+    if error is not None:
+        if "path does not exist" in error:
+            return ["Check the path spelling and try again."]
+        if "path is not a directory" in error:
+            return ["Pass the project directory path instead of a single file."]
+        if "Argument error:" in error:
+            return ["Run pyenv-doctor --help to review the available arguments."]
+        return []
+
+    suggestions: list[str] = []
+
+    # If nothing was detected, the safest first step is to confirm the scan location.
+    if not detected_files:
+        suggestions.append("Verify that you are scanning the project root directory.")
+
+    # pyproject.toml often defines the project's preferred install and run workflow.
+    if "pyproject.toml" in detected_files:
+        suggestions.append("Open pyproject.toml to check how this project should be installed or run.")
+
+    # Pipfile usually means the project expects a Pipenv-style workflow.
+    if "Pipfile" in detected_files:
+        suggestions.append("Open Pipfile to review the project's dependencies and environment settings.")
+
+    # poetry.lock usually appears in Poetry-based projects.
+    if "poetry.lock" in detected_files:
+        suggestions.append("If this project uses Poetry, review pyproject.toml and try poetry install.")
+
+    # uv.lock usually appears in uv-managed projects.
+    if "uv.lock" in detected_files:
+        suggestions.append("If this project uses uv, review the project instructions and try uv sync.")
+
+    # environment.yml usually points to a Conda environment definition.
+    if "environment.yml" in detected_files:
+        suggestions.append("If this project uses Conda, create the environment from environment.yml before running it.")
+
+    # .python-version often records the expected Python version for the project.
+    if ".python-version" in detected_files:
+        suggestions.append("Check .python-version to see which Python version this project expects.")
+
+    # Only suggest a virtual environment when one is not already active.
+    if "requirements.txt" in detected_files and not virtual_environment_detected:
+        suggestions.append("Create and activate a virtual environment before installing dependencies.")
+
+    return suggestions
+
+
+def build_result(
+    scanned_directory: str | None = None,
+    found_files: list[str] | None = None,
+    error: str | None = None,
+    virtual_environment_detected: bool | None = None,
+) -> dict[str, object]:
+    """Build a structured result that works for both text and JSON output."""
+    # Default to an empty list so the JSON structure stays predictable.
+    detected_files = found_files if found_files is not None else []
+    env_detected = (
+        virtual_environment_detected
+        if virtual_environment_detected is not None
+        else is_virtual_environment_detected()
+    )
+    suggestions = build_suggestions(
+        found_files=detected_files,
+        error=error,
+        virtual_environment_detected=env_detected,
+    )
+
+    return {
+        "scanned_directory": scanned_directory,
+        "found_files": detected_files,
+        "looks_like_python_project": bool(detected_files),
+        "virtual_environment_detected": env_detected,
+        "error": error,
+        "suggestions": suggestions,
+    }
+
+
+def print_json_result(result: dict[str, object]) -> None:
+    """Print a JSON result with stable formatting for humans and scripts."""
+    # Indented JSON stays readable while still being valid machine output.
+    print(json.dumps(result, indent=2))
+
+
+def print_project_result(scan_path: Path, found_files: list[str]) -> None:
+    """Print the project file detection result in a clear format."""
+    print(f"Scanned directory: {scan_path}")
+    print()
+    print("Project file detection:")
+
+    # Print the status for every marker file in a fixed order.
+    for file_name in PROJECT_MARKER_FILES:
+        status = "found" if file_name in found_files else "not found"
+        print(f"- {file_name}: {status}")
+
+    print()
+
+    # If at least one marker file exists, the directory probably is a Python project.
+    if found_files:
+        print("Conclusion: this looks like a Python project")
+        print(f"Reason: detected {', '.join(found_files)}")
+    else:
+        print("Conclusion: no clear Python project markers were found")
+        print("Details: common Python project files were not found in this directory.")
+
+
+def print_virtual_environment_result(virtual_environment_detected: bool) -> None:
+    """Print the virtual environment detection result."""
+    print()
+    print("Virtual environment detection:")
+
+    if virtual_environment_detected:
+        print("Virtual environment: detected")
+    else:
+        print("Virtual environment: not detected")
+        print("Recommendation: use venv or Conda for an isolated Python environment")
+
+
+def print_suggestions(suggestions: list[str], stream=None) -> None:
+    """Print a short suggestions section after the main result."""
+    output_stream = stream if stream is not None else sys.stdout
+    print(file=output_stream)
+    print("Suggestions:", file=output_stream)
+
+    if not suggestions:
+        print("- No immediate suggestions.", file=output_stream)
+        return
+
+    # Keep each suggestion short and actionable for beginners.
+    for suggestion in suggestions:
+        print(f"- {suggestion}", file=output_stream)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the program and return an exit code."""
+    # Allow tests and the console script to pass arguments explicitly when needed.
+    arguments = argv if argv is not None else sys.argv[1:]
+
+    # Parse arguments now so the CLI structure stays ready for small future changes.
+    parser = build_parser()
+    # Detect JSON mode early so parse errors can also return JSON when requested.
+    parser.json_output = "--json" in arguments
+    args = parser.parse_args(arguments)
+    virtual_environment_detected = is_virtual_environment_detected()
+
+    # Scan either the provided directory or, by default, the current working directory.
+    scan_path, error_message, displayed_path = get_scan_path(args.path)
+
+    # Keep the existing non-zero exit behavior for invalid paths.
+    if error_message is not None:
+        error_result = build_result(
+            scanned_directory=displayed_path,
+            error=error_message,
+            virtual_environment_detected=virtual_environment_detected,
+        )
+        if args.json:
+            print_json_result(error_result)
+        else:
+            print(error_message, file=sys.stderr)
+            print_suggestions(error_result["suggestions"], stream=sys.stderr)
+        return 1
+
+    # At this point the scan path is valid and safe to inspect.
+    assert scan_path is not None
+    found_files = find_marker_files(scan_path)
+    result = build_result(
+        scanned_directory=displayed_path,
+        found_files=found_files,
+        virtual_environment_detected=virtual_environment_detected,
+    )
+
+    # JSON mode returns only structured data and skips the human-readable text blocks.
+    if args.json:
+        print_json_result(result)
+        return 0
+
+    print_project_result(scan_path, found_files)
+    print_virtual_environment_result(virtual_environment_detected)
+    print_suggestions(result["suggestions"])
+    return 0
+
+
+if __name__ == "__main__":
+    # Allow direct execution with `python main.py` and return a process exit code.
+    sys.exit(main())

python_project_doctor_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,298 @@
+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).

python_project_doctor_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+main.py,sha256=ewnCyaxX-AMw-F4-Us-nngTuYeFmZf3Pwnjb2ZWnRmw,11597
+python_project_doctor_cli-0.1.0.dist-info/licenses/LICENSE,sha256=nakW2OxV8ZBQL-coZ-3Oi6zF7AGdb_SJtEkunWfh6Mc,1075
+python_project_doctor_cli-0.1.0.dist-info/METADATA,sha256=wIYG9aNTmyzyRyir9f6wDVT9Pp0PkGpPTkHkZiQActc,7523
+python_project_doctor_cli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_project_doctor_cli-0.1.0.dist-info/entry_points.txt,sha256=ZLBoYWY0Ip48JbNKXdHRYkJXknwgFBnmQgs2dfvaXWI,43
+python_project_doctor_cli-0.1.0.dist-info/top_level.txt,sha256=ZAMgPdWghn6xTRBO6Kc3ML1y3ZrZLnjZlqbboKXc_AE,5
+python_project_doctor_cli-0.1.0.dist-info/RECORD,,

python_project_doctor_cli-0.1.0.dist-info/WHEEL

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

python_project_doctor_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pyenv-doctor = main:main

python_project_doctor_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+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.

python_project_doctor_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+main