ghps 0.2__tar.gz → 0.4__tar.gz

{ghps-0.2 → ghps-0.4}/CHANGELOG.md

@@ -5,6 +5,23 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+## [0.4] - 2026-05-08
+### Added
+- `GHPSError` class
+- `GHPSValidationError` class
+- `GHPSRuntimeError` class
+- Port error messages
+### Changed
+- Test system modified
+## [0.3] - 2026-04-05
+### Added
+- `auto_open` parameter
+- `--auto-open` CLI argument
+- Random port support
+### Changed
+- Test system modified
+- CLI error messages updated
+- `README.md` updated
 ## [0.2] - 2026-03-19
 ### Added
 - Logo
@@ -18,7 +35,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Command line interface
 - Test system
 
-[Unreleased]: https://github.com/sepandhaghighi/ghps/compare/v0.2...dev
+[Unreleased]: https://github.com/sepandhaghighi/ghps/compare/v0.4...dev
+[0.4]: https://github.com/sepandhaghighi/ghps/compare/v0.3...v0.4
+[0.3]: https://github.com/sepandhaghighi/ghps/compare/v0.2...v0.3
 [0.2]: https://github.com/sepandhaghighi/ghps/compare/v0.1...v0.2
 [0.1]: https://github.com/sepandhaghighi/ghps/compare/bc0a425...v0.1
 

{ghps-0.2 → ghps-0.4}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: ghps
-Version: 0.2
+Version: 0.4
 Summary: Ghps: A Minimal GitHub Pages Simulator for Local Development
 Home-page: https://github.com/sepandhaghighi/ghps
-Download-URL: https://github.com/sepandhaghighi/ghps/tarball/v0.2
+Download-URL: https://github.com/sepandhaghighi/ghps/tarball/v0.4
 Author: Sepand Haghighi
 Author-email: me@sepand.tech
 License: MIT
@@ -101,13 +101,13 @@ Dynamic: summary
 ## Installation		
 
 ### Source Code
-- Download [Version 0.2](https://github.com/sepandhaghighi/ghps/archive/v0.2.zip) or [Latest Source](https://github.com/sepandhaghighi/ghps/archive/dev.zip)
+- Download [Version 0.4](https://github.com/sepandhaghighi/ghps/archive/v0.4.zip) or [Latest Source](https://github.com/sepandhaghighi/ghps/archive/dev.zip)
 - `pip install .`				
 
 ### PyPI
 
 - Check [Python Packaging User Guide](https://packaging.python.org/installing/)     
-- `pip install ghps==0.2`						
+- `pip install ghps==0.4`						
 
 
 ## Usage
@@ -130,6 +130,9 @@ ghps --port=8080 --no-cache --no-threaded
 | `--no-strict` | Enable `.html` fallback| Strict mode enabled |
 | `--no-cache` | Disable HTTP caching headers | Cache enabled |
 | `--no-threaded` | Disable threaded server | Threaded enabled |
+| `--auto-open` | Automatically open the server URL | Disable |
+
+ℹ️ You can set `--port=0` to let the OS automatically select an available port
 
 
 ### Library
@@ -144,6 +147,7 @@ server = GHPageServer(
     strict=True,
     no_cache=False,
     threaded=True,
+	auto_open=True,
 )
 
 server.start()
@@ -159,6 +163,9 @@ server.start()
 | `strict` | `bool` | Enforce GitHub-like routing behavior | `True` |
 | `no_cache` | `bool` | Disable cache headers | `False` |
 | `threaded` | `bool` | Enable threaded request handling | `True` |
+| `auto_open` | `bool` | Automatically open the server URL | `False` |
+
+ℹ️ You can set `port=0` to let the OS automatically select an available port
 
 ## Issues & Bug Reports			
 
@@ -209,6 +216,23 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+## [0.4] - 2026-05-08
+### Added
+- `GHPSError` class
+- `GHPSValidationError` class
+- `GHPSRuntimeError` class
+- Port error messages
+### Changed
+- Test system modified
+## [0.3] - 2026-04-05
+### Added
+- `auto_open` parameter
+- `--auto-open` CLI argument
+- Random port support
+### Changed
+- Test system modified
+- CLI error messages updated
+- `README.md` updated
 ## [0.2] - 2026-03-19
 ### Added
 - Logo
@@ -222,7 +246,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Command line interface
 - Test system
 
-[Unreleased]: https://github.com/sepandhaghighi/ghps/compare/v0.2...dev
+[Unreleased]: https://github.com/sepandhaghighi/ghps/compare/v0.4...dev
+[0.4]: https://github.com/sepandhaghighi/ghps/compare/v0.3...v0.4
+[0.3]: https://github.com/sepandhaghighi/ghps/compare/v0.2...v0.3
 [0.2]: https://github.com/sepandhaghighi/ghps/compare/v0.1...v0.2
 [0.1]: https://github.com/sepandhaghighi/ghps/compare/bc0a425...v0.1
 

{ghps-0.2 → ghps-0.4}/README.md

@@ -50,13 +50,13 @@
 ## Installation		
 
 ### Source Code
-- Download [Version 0.2](https://github.com/sepandhaghighi/ghps/archive/v0.2.zip) or [Latest Source](https://github.com/sepandhaghighi/ghps/archive/dev.zip)
+- Download [Version 0.4](https://github.com/sepandhaghighi/ghps/archive/v0.4.zip) or [Latest Source](https://github.com/sepandhaghighi/ghps/archive/dev.zip)
 - `pip install .`				
 
 ### PyPI
 
 - Check [Python Packaging User Guide](https://packaging.python.org/installing/)     
-- `pip install ghps==0.2`						
+- `pip install ghps==0.4`						
 
 
 ## Usage
@@ -79,6 +79,9 @@ ghps --port=8080 --no-cache --no-threaded
 | `--no-strict` | Enable `.html` fallback| Strict mode enabled |
 | `--no-cache` | Disable HTTP caching headers | Cache enabled |
 | `--no-threaded` | Disable threaded server | Threaded enabled |
+| `--auto-open` | Automatically open the server URL | Disable |
+
+ℹ️ You can set `--port=0` to let the OS automatically select an available port
 
 
 ### Library
@@ -93,6 +96,7 @@ server = GHPageServer(
     strict=True,
     no_cache=False,
     threaded=True,
+	auto_open=True,
 )
 
 server.start()
@@ -108,6 +112,9 @@ server.start()
 | `strict` | `bool` | Enforce GitHub-like routing behavior | `True` |
 | `no_cache` | `bool` | Disable cache headers | `False` |
 | `threaded` | `bool` | Enable threaded request handling | `True` |
+| `auto_open` | `bool` | Automatically open the server URL | `False` |
+
+ℹ️ You can set `port=0` to let the OS automatically select an available port
 
 ## Issues & Bug Reports			
 

{ghps-0.2 → ghps-0.4}/SECURITY.md

@@ -4,8 +4,8 @@
 
 | Version       | Supported          |
 | ------------- | ------------------ |
-| 0.2           | :white_check_mark: |
-| < 0.2         | :x:                |
+| 0.4           | :white_check_mark: |
+| < 0.4         | :x:                |
 
 ## Reporting a Vulnerability
 

{ghps-0.2 → ghps-0.4}/dev-requirements.txt

@@ -5,4 +5,4 @@ pytest-cov>=2.6.1
 setuptools>=40.8.0
 vulture>=1.0
 bandit>=1.5.1
-pydocstyle>=3.0.0
+pydocstyle>=6.3.0

ghps-0.4/ghps/__init__.py

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""ghps modules."""
+from .params import GHPS_VERSION
+from .errors import GHPSError, GHPSRuntimeError, GHPSValidationError
+from .server import GHPageServer
+__version__ = GHPS_VERSION
+
+__all__ = ["GHPageServer", "GHPSError", "GHPSRuntimeError", "GHPSValidationError"]

{ghps-0.2 → ghps-0.4}/ghps/cli.py

@@ -5,9 +5,21 @@ import sys
 import argparse
 from pathlib import Path
 from .params import GHPS_VERSION
+from .errors import GHPSError
 from .server import GHPageServer
 
 
+def _print_cli_error(message: str, exit_code: int = 1) -> None:
+    """
+    Print a formatted CLI error message and exit.
+
+    :param message: Error message to display.
+    :param exit_code: Exit status code (default: 1).
+    """
+    print(f"[GHPS ERROR] {message}", file=sys.stderr)
+    sys.exit(exit_code)
+
+
 def _parse_args() -> argparse.Namespace:
     """Parse arguments."""
     parser = argparse.ArgumentParser(
@@ -57,29 +69,34 @@ def _parse_args() -> argparse.Namespace:
         help="Disable threaded server"
     )
 
+    parser.add_argument(
+        "--auto-open",
+        action="store_true",
+        help="Automatically open the server URL"
+    )
+
     args = parser.parse_args()
     return args
 
 
 def main() -> None:
     """CLI main function."""
-    args = _parse_args()
-
-    if args.version:
-        print(GHPS_VERSION)
-    else:
-        directory = Path(args.directory).resolve()
-
-        if not directory.exists():
-            print("Error: Directory does not exist.")
-            sys.exit(1)
-
-        server = GHPageServer(
-            directory=str(directory),
-            port=args.port,
-            base_path=args.base_path,
-            strict=not args.no_strict,
-            no_cache=args.no_cache,
-            threaded=not args.no_threaded,
-        )
-        server.start()
+    try:
+        args = _parse_args()
+        if args.version:
+            print(GHPS_VERSION)
+        else:
+            server = GHPageServer(
+                directory=args.directory,
+                port=args.port,
+                base_path=args.base_path,
+                strict=not args.no_strict,
+                no_cache=args.no_cache,
+                threaded=not args.no_threaded,
+                auto_open=args.auto_open,
+            )
+            server.start()
+    except GHPSError as e:
+        _print_cli_error(str(e))
+    except Exception as e:
+        _print_cli_error(f"Unexpected error: {e}")

ghps-0.4/ghps/errors.py

@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+"""ghps errors."""
+
+
+class GHPSError(Exception):
+    """Base exception for GHPS."""
+
+
+class GHPSValidationError(GHPSError, ValueError):
+    """Raised for invalid input parameters."""
+
+
+class GHPSRuntimeError(GHPSError):
+    """Raised for runtime errors during server execution."""

{ghps-0.2 → ghps-0.4}/ghps/params.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 """ghps params."""
 
-GHPS_VERSION = "0.2"
+GHPS_VERSION = "0.4"
 
 INVALID_DIRECTORY_TYPE_ERROR = "`directory` must be str or pathlib.Path."
 DIRECTORY_NOT_FOUND_ERROR = "`directory` does not exist."
@@ -16,3 +16,9 @@ INVALID_BASE_PATH_FORMAT_ERROR = "`base_path` must start with '/' or be empty."
 INVALID_STRICT_TYPE_ERROR = "`strict` must be bool."
 INVALID_NO_CACHE_TYPE_ERROR = "`no_cache` must be bool."
 INVALID_THREADED_TYPE_ERROR = "`threaded` must be bool."
+INVALID_AUTO_OPEN_TYPE_ERROR = "`auto_open` must be bool."
+
+PORT_IN_USE_ERROR = "`port` is already in use. Try another port or use 0."
+PORT_ACCESS_DENIED_ERROR = "`port` access denied. Try a different port or check permissions."
+PORT_ADDRESS_NOT_AVAILABLE_ERROR = "`port` address is not available. Check network configuration."
+PORT_BIND_GENERIC_ERROR = "Failed to start server on port `{port}`: {error}"

{ghps-0.2 → ghps-0.4}/ghps/server.py

@@ -3,6 +3,8 @@
 
 import http.server
 import socketserver
+import webbrowser
+import errno
 from typing import Optional, Any
 from pathlib import Path
 from urllib.parse import unquote
@@ -17,7 +19,15 @@ from .params import (
     INVALID_STRICT_TYPE_ERROR,
     INVALID_NO_CACHE_TYPE_ERROR,
     INVALID_THREADED_TYPE_ERROR,
+    INVALID_AUTO_OPEN_TYPE_ERROR
 )
+from .params import (
+    PORT_IN_USE_ERROR,
+    PORT_ACCESS_DENIED_ERROR,
+    PORT_ADDRESS_NOT_AVAILABLE_ERROR,
+    PORT_BIND_GENERIC_ERROR,
+)
+from .errors import GHPSValidationError, GHPSRuntimeError
 
 
 def _validate_inputs(
@@ -27,6 +37,7 @@ def _validate_inputs(
     strict: Any,
     no_cache: Any,
     threaded: Any,
+    auto_open: Any,
 ):
     """
     Validate GHPageServer inputs.
@@ -37,37 +48,65 @@ def _validate_inputs(
     :param strict: If False, enables automatic ".html" resolution.
     :param no_cache: If True, disables client-side caching.
     :param threaded: If True, handles requests using threads.
+    :param auto_open: If True, automatically opens the server URL in the default web browser.
     """
     if not isinstance(directory, (str, Path)):
-        raise ValueError(INVALID_DIRECTORY_TYPE_ERROR)
+        raise GHPSValidationError(INVALID_DIRECTORY_TYPE_ERROR)
 
     directory = Path(directory)
     if not directory.exists():
-        raise ValueError(DIRECTORY_NOT_FOUND_ERROR)
+        raise GHPSValidationError(DIRECTORY_NOT_FOUND_ERROR)
 
     if not directory.is_dir():
-        raise ValueError(DIRECTORY_NOT_DIR_ERROR)
+        raise GHPSValidationError(DIRECTORY_NOT_DIR_ERROR)
 
     if not isinstance(port, int):
-        raise ValueError(INVALID_PORT_TYPE_ERROR)
+        raise GHPSValidationError(INVALID_PORT_TYPE_ERROR)
 
-    if not (1 <= port <= 65535):
-        raise ValueError(INVALID_PORT_RANGE_ERROR)
+    if not (0 <= port <= 65535):
+        raise GHPSValidationError(INVALID_PORT_RANGE_ERROR)
 
     if not isinstance(base_path, str):
-        raise ValueError(INVALID_BASE_PATH_TYPE_ERROR)
+        raise GHPSValidationError(INVALID_BASE_PATH_TYPE_ERROR)
 
     if base_path and not base_path.startswith("/"):
-        raise ValueError(INVALID_BASE_PATH_FORMAT_ERROR)
+        raise GHPSValidationError(INVALID_BASE_PATH_FORMAT_ERROR)
 
     if not isinstance(strict, bool):
-        raise ValueError(INVALID_STRICT_TYPE_ERROR)
+        raise GHPSValidationError(INVALID_STRICT_TYPE_ERROR)
 
     if not isinstance(no_cache, bool):
-        raise ValueError(INVALID_NO_CACHE_TYPE_ERROR)
+        raise GHPSValidationError(INVALID_NO_CACHE_TYPE_ERROR)
 
     if not isinstance(threaded, bool):
-        raise ValueError(INVALID_THREADED_TYPE_ERROR)
+        raise GHPSValidationError(INVALID_THREADED_TYPE_ERROR)
+
+    if not isinstance(auto_open, bool):
+        raise GHPSValidationError(INVALID_AUTO_OPEN_TYPE_ERROR)
+
+
+def _handle_bind_error(port: int, e: OSError) -> None:
+    """
+    Handle socket binding errors and raise a user-friendly runtime exception.
+
+    :param port: Port number that the server attempted to bind to.
+    :param e: Original OSError raised during binding.
+    """
+    err = getattr(e, "errno", None)
+
+    if err == errno.EADDRINUSE:
+        raise GHPSRuntimeError(PORT_IN_USE_ERROR) from e
+
+    elif err in (errno.EACCES, errno.EPERM):
+        raise GHPSRuntimeError(PORT_ACCESS_DENIED_ERROR) from e
+
+    elif err == errno.EADDRNOTAVAIL:
+        raise GHPSRuntimeError(PORT_ADDRESS_NOT_AVAILABLE_ERROR) from e
+
+    else:
+        raise GHPSRuntimeError(
+            PORT_BIND_GENERIC_ERROR.format(port=port, error=e)
+        ) from e
 
 
 class _GHRequestHandler(http.server.SimpleHTTPRequestHandler):
@@ -178,6 +217,7 @@ class GHPageServer:
         strict: bool = True,
         no_cache: bool = False,
         threaded: bool = True,
+        auto_open: bool = False,
     ):
         """
         Initialize the server.
@@ -188,6 +228,7 @@ class GHPageServer:
         :param strict: If False, enables automatic ".html" resolution.
         :param no_cache: If True, disables client-side caching.
         :param threaded: If True, handles requests using threads.
+        :param auto_open: If True, automatically opens the server URL in the default web browser.
         """
         _validate_inputs(
             directory=directory,
@@ -196,6 +237,7 @@ class GHPageServer:
             strict=strict,
             no_cache=no_cache,
             threaded=threaded,
+            auto_open=auto_open,
         )
         self._directory = str(Path(directory).resolve())
         self._port = port
@@ -203,6 +245,7 @@ class GHPageServer:
         self._strict = strict
         self._no_cache = no_cache
         self._threaded = threaded
+        self._auto_open = auto_open
         self._httpd = None
 
     def start(self) -> None:
@@ -222,13 +265,22 @@ class GHPageServer:
 
         server_cls = _ThreadedTCPServer if self._threaded else socketserver.TCPServer
 
-        self._httpd = server_cls(("", self._port), handler)
-
-        print(f"Serving at http://localhost:{self._port}{self._base_path}")
+        try:
+            self._httpd = server_cls(("", self._port), handler)
+        except OSError as e:
+            _handle_bind_error(self._port, e)
+        self._port = self._httpd.server_address[1]
+        url = f"http://localhost:{self._port}{self._base_path}"
+        print(f"Serving at {url}")
         print(f"Directory: {self._directory}")
         print(f"Strict mode: {'ON' if self._strict else 'OFF'}")
         print(f"Cache disabled: {'YES' if self._no_cache else 'NO'}")
 
+        if self._auto_open:
+            try:
+                webbrowser.open(url)
+            except Exception:
+                print("[GHPS ERROR]: Failed to open browser automatically")
         try:
             self._httpd.serve_forever()
         except KeyboardInterrupt:

{ghps-0.2 → ghps-0.4}/ghps.egg-info/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: ghps
-Version: 0.2
+Version: 0.4
 Summary: Ghps: A Minimal GitHub Pages Simulator for Local Development
 Home-page: https://github.com/sepandhaghighi/ghps
-Download-URL: https://github.com/sepandhaghighi/ghps/tarball/v0.2
+Download-URL: https://github.com/sepandhaghighi/ghps/tarball/v0.4
 Author: Sepand Haghighi
 Author-email: me@sepand.tech
 License: MIT
@@ -101,13 +101,13 @@ Dynamic: summary
 ## Installation		
 
 ### Source Code
-- Download [Version 0.2](https://github.com/sepandhaghighi/ghps/archive/v0.2.zip) or [Latest Source](https://github.com/sepandhaghighi/ghps/archive/dev.zip)
+- Download [Version 0.4](https://github.com/sepandhaghighi/ghps/archive/v0.4.zip) or [Latest Source](https://github.com/sepandhaghighi/ghps/archive/dev.zip)
 - `pip install .`				
 
 ### PyPI
 
 - Check [Python Packaging User Guide](https://packaging.python.org/installing/)     
-- `pip install ghps==0.2`						
+- `pip install ghps==0.4`						
 
 
 ## Usage
@@ -130,6 +130,9 @@ ghps --port=8080 --no-cache --no-threaded
 | `--no-strict` | Enable `.html` fallback| Strict mode enabled |
 | `--no-cache` | Disable HTTP caching headers | Cache enabled |
 | `--no-threaded` | Disable threaded server | Threaded enabled |
+| `--auto-open` | Automatically open the server URL | Disable |
+
+ℹ️ You can set `--port=0` to let the OS automatically select an available port
 
 
 ### Library
@@ -144,6 +147,7 @@ server = GHPageServer(
     strict=True,
     no_cache=False,
     threaded=True,
+	auto_open=True,
 )
 
 server.start()
@@ -159,6 +163,9 @@ server.start()
 | `strict` | `bool` | Enforce GitHub-like routing behavior | `True` |
 | `no_cache` | `bool` | Disable cache headers | `False` |
 | `threaded` | `bool` | Enable threaded request handling | `True` |
+| `auto_open` | `bool` | Automatically open the server URL | `False` |
+
+ℹ️ You can set `port=0` to let the OS automatically select an available port
 
 ## Issues & Bug Reports			
 
@@ -209,6 +216,23 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+## [0.4] - 2026-05-08
+### Added
+- `GHPSError` class
+- `GHPSValidationError` class
+- `GHPSRuntimeError` class
+- Port error messages
+### Changed
+- Test system modified
+## [0.3] - 2026-04-05
+### Added
+- `auto_open` parameter
+- `--auto-open` CLI argument
+- Random port support
+### Changed
+- Test system modified
+- CLI error messages updated
+- `README.md` updated
 ## [0.2] - 2026-03-19
 ### Added
 - Logo
@@ -222,7 +246,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Command line interface
 - Test system
 
-[Unreleased]: https://github.com/sepandhaghighi/ghps/compare/v0.2...dev
+[Unreleased]: https://github.com/sepandhaghighi/ghps/compare/v0.4...dev
+[0.4]: https://github.com/sepandhaghighi/ghps/compare/v0.3...v0.4
+[0.3]: https://github.com/sepandhaghighi/ghps/compare/v0.2...v0.3
 [0.2]: https://github.com/sepandhaghighi/ghps/compare/v0.1...v0.2
 [0.1]: https://github.com/sepandhaghighi/ghps/compare/bc0a425...v0.1
 

{ghps-0.2 → ghps-0.4}/ghps.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ setup.py
 ghps/__init__.py
 ghps/__main__.py
 ghps/cli.py
+ghps/errors.py
 ghps/params.py
 ghps/server.py
 ghps.egg-info/PKG-INFO

{ghps-0.2 → ghps-0.4}/setup.py

@@ -32,7 +32,7 @@ def read_description() -> str:
 setup(
     name='ghps',
     packages=['ghps'],
-    version='0.2',
+    version='0.4',
     description='Ghps: A Minimal GitHub Pages Simulator for Local Development',
     long_description=read_description(),
     long_description_content_type='text/markdown',
@@ -40,7 +40,7 @@ setup(
     author='Sepand Haghighi',
     author_email='me@sepand.tech',
     url='https://github.com/sepandhaghighi/ghps',
-    download_url='https://github.com/sepandhaghighi/ghps/tarball/v0.2',
+    download_url='https://github.com/sepandhaghighi/ghps/tarball/v0.4',
     keywords="github gh-pages static-server static-hosting development server local http simulator testing cli python",
     project_urls={
         'Source': 'https://github.com/sepandhaghighi/ghps'

{ghps-0.2 → ghps-0.4}/tests/test_cli.py

@@ -110,3 +110,17 @@ def test_cli_invalid_directory(monkeypatch):
 
     with pytest.raises(SystemExit):
         ghps.cli.main()
+
+
+@patch("ghps.cli.GHPageServer")
+@patch("sys.stderr")
+def test_cli_unexpected_error(mock_stderr, mock_server_cls):
+    mock_server = mock_server_cls.return_value
+    mock_server.start.side_effect = Exception("boom")
+    test_args = ["ghps"]
+    with patch("sys.argv", test_args):
+        with pytest.raises(SystemExit) as exc:
+            ghps.cli.main()
+    assert exc.value.code == 1
+    written = "".join(call.args[0] for call in mock_stderr.write.call_args_list)
+    assert "[GHPS ERROR] Unexpected error: boom" in written

ghps-0.4/tests/test_error.py

@@ -0,0 +1,209 @@
+# -*- coding: utf-8 -*-
+import errno
+import pytest
+from unittest.mock import patch
+from ghps import GHPageServer, GHPSValidationError, GHPSRuntimeError
+
+
+def test_invalid_directory_type():
+    with pytest.raises(GHPSValidationError, match="`directory` must be str or pathlib.Path."):
+        GHPageServer(
+            directory=123,
+            port=8000,
+            base_path="",
+            strict=True,
+            no_cache=False,
+            threaded=True,
+        )
+
+
+def test_directory_not_found():
+    with pytest.raises(GHPSValidationError, match="`directory` does not exist."):
+        GHPageServer(
+            directory="__not_existing_dir__",
+            port=8000,
+            base_path="",
+            strict=True,
+            no_cache=False,
+            threaded=True,
+        )
+
+
+def test_directory_not_directory(tmp_path):
+    file_path = tmp_path / "file.txt"
+    file_path.write_text("data")
+
+    with pytest.raises(GHPSValidationError, match="`directory` must be a valid directory."):
+        GHPageServer(
+            directory=file_path,
+            port=8000,
+            base_path="",
+            strict=True,
+            no_cache=False,
+            threaded=True,
+        )
+
+
+def test_invalid_port_type(tmp_path):
+    with pytest.raises(GHPSValidationError, match="`port` must be int."):
+        GHPageServer(
+            directory=tmp_path,
+            port="8000",
+            base_path="",
+            strict=True,
+            no_cache=False,
+            threaded=True,
+        )
+
+
+def test_invalid_port_range(tmp_path):
+    with pytest.raises(GHPSValidationError, match="`port` must be between 1 and 65535."):
+        GHPageServer(
+            directory=tmp_path,
+            port=70000,
+            base_path="",
+            strict=True,
+            no_cache=False,
+            threaded=True,
+        )
+
+
+def test_invalid_base_path_type(tmp_path):
+    with pytest.raises(GHPSValidationError, match="`base_path` must be str."):
+        GHPageServer(
+            directory=tmp_path,
+            port=8000,
+            base_path=123,
+            strict=True,
+            no_cache=False,
+            threaded=True,
+        )
+
+
+def test_invalid_base_path_format(tmp_path):
+    with pytest.raises(GHPSValidationError, match="`base_path` must start with '/' or be empty."):
+        GHPageServer(
+            directory=tmp_path,
+            port=8000,
+            base_path="docs",
+            strict=True,
+            no_cache=False,
+            threaded=True,
+        )
+
+
+def test_invalid_strict_type(tmp_path):
+    with pytest.raises(GHPSValidationError, match="`strict` must be bool."):
+        GHPageServer(
+            directory=tmp_path,
+            port=8000,
+            base_path="",
+            strict="yes",
+            no_cache=False,
+            threaded=True,
+        )
+
+
+def test_invalid_no_cache_type(tmp_path):
+    with pytest.raises(GHPSValidationError, match="`no_cache` must be bool."):
+        GHPageServer(
+            directory=tmp_path,
+            port=8000,
+            base_path="",
+            strict=True,
+            no_cache="false",
+            threaded=True,
+        )
+
+
+def test_invalid_threaded_type(tmp_path):
+    with pytest.raises(GHPSValidationError, match="`threaded` must be bool."):
+        GHPageServer(
+            directory=tmp_path,
+            port=8000,
+            base_path="",
+            strict=True,
+            no_cache=False,
+            threaded="true",
+        )
+
+
+def test_invalid_auto_open_type(tmp_path):
+    with pytest.raises(GHPSValidationError, match="`auto_open` must be bool."):
+        GHPageServer(
+            directory=tmp_path,
+            port=8000,
+            base_path="",
+            strict=True,
+            no_cache=False,
+            threaded=True,
+            auto_open="true",
+        )
+
+
+@patch("ghps.server.webbrowser.open", side_effect=Exception("boom"))
+@patch("ghps.server._ThreadedTCPServer")
+@patch("builtins.print")
+def test_auto_open_failure_logs_error(mock_print, mock_server_cls, mock_web_open, tmp_path):
+    mock_server = mock_server_cls.return_value
+    mock_server.server_address = ("127.0.0.1", 8000)
+    mock_server.serve_forever.side_effect = KeyboardInterrupt
+    server = GHPageServer(
+        directory=tmp_path,
+        port=8000,
+        auto_open=True,
+    )
+    server.start()
+    mock_web_open.assert_called_once_with("http://localhost:8000")
+    assert any(
+        "[GHPS ERROR]: Failed to open browser automatically" in str(call)
+        for call in mock_print.call_args_list
+    )
+
+
+@patch("ghps.server._ThreadedTCPServer")
+def test_port_in_use_error(mock_server_cls, tmp_path):
+    mock_server_cls.side_effect = OSError(errno.EADDRINUSE, "in use")
+
+    server = GHPageServer(directory=tmp_path, port=8000)
+
+    with pytest.raises(GHPSRuntimeError) as exc:
+        server.start()
+
+    assert "`port` is already in use. Try another port or use 0." in str(exc.value)
+
+
+@patch("ghps.server._ThreadedTCPServer")
+def test_port_access_denied_error(mock_server_cls, tmp_path):
+    mock_server_cls.side_effect = OSError(errno.EACCES, "denied")
+
+    server = GHPageServer(directory=tmp_path, port=80)
+
+    with pytest.raises(GHPSRuntimeError) as exc:
+        server.start()
+
+    assert "`port` access denied. Try a different port or check permissions." in str(exc.value)
+
+
+@patch("ghps.server._ThreadedTCPServer")
+def test_port_generic_error(mock_server_cls, tmp_path):
+    mock_server_cls.side_effect = OSError(9999, "boom")
+
+    server = GHPageServer(directory=tmp_path, port=8000)
+
+    with pytest.raises(GHPSRuntimeError) as exc:
+        server.start()
+
+    assert "Failed to start server on port" in str(exc.value)
+
+
+@patch("ghps.server._ThreadedTCPServer")
+def test_port_address_not_available_error(mock_server_cls, tmp_path):
+    mock_server_cls.side_effect = OSError(errno.EADDRNOTAVAIL, "not-available")
+
+    server = GHPageServer(directory=tmp_path, port=80)
+
+    with pytest.raises(GHPSRuntimeError) as exc:
+        server.start()
+
+    assert "`port` address is not available. Check network configuration." in str(exc.value)

{ghps-0.2 → ghps-0.4}/tests/test_server.py

@@ -128,3 +128,52 @@ def test_keyboard_interrupt(capsys):
 
     captured = capsys.readouterr()
     assert "Server stopped." in captured.out
+
+
+@patch("ghps.server.webbrowser.open")
+@patch("ghps.server._ThreadedTCPServer")
+def test_auto_open_enabled(mock_server_cls, mock_web_open, tmp_path):
+    mock_server = mock_server_cls.return_value
+    mock_server.server_address = ("127.0.0.1", 8000)
+    mock_server.serve_forever.side_effect = KeyboardInterrupt
+
+    server = GHPageServer(
+        directory=tmp_path,
+        port=8000,
+        auto_open=True,
+    )
+
+    server.start()
+
+    mock_web_open.assert_called_once_with("http://localhost:8000")
+
+
+@patch("ghps.server.webbrowser.open")
+@patch("ghps.server._ThreadedTCPServer")
+def test_auto_open_disabled(mock_server_cls, mock_web_open, tmp_path):
+    mock_server = mock_server_cls.return_value
+    mock_server.server_address = ("127.0.0.1", 8000)
+    mock_server.serve_forever.side_effect = KeyboardInterrupt
+
+    server = GHPageServer(
+        directory=tmp_path,
+        port=8000,
+        auto_open=False,
+    )
+
+    server.start()
+
+    mock_web_open.assert_not_called()
+
+
+@patch("ghps.server._ThreadedTCPServer")
+def test_random_port_resolution(mock_server_cls, tmp_path):
+    mock_server = mock_server_cls.return_value
+    mock_server.server_address = ("127.0.0.1", 54321)
+    mock_server.serve_forever.side_effect = KeyboardInterrupt
+    server = GHPageServer(
+        directory=tmp_path,
+        port=0,
+    )
+    server.start()
+    assert server._port == 54321

ghps-0.2/ghps/__init__.py

@@ -1,7 +0,0 @@
-# -*- coding: utf-8 -*-
-"""ghps modules."""
-from .params import GHPS_VERSION
-from .server import GHPageServer
-__version__ = GHPS_VERSION
-
-__all__ = ["GHPageServer"]

ghps-0.2/tests/test_error.py

@@ -1,126 +0,0 @@
-# -*- coding: utf-8 -*-
-import pytest
-from ghps import GHPageServer
-
-
-def test_invalid_directory_type():
-    with pytest.raises(ValueError, match="`directory` must be str or pathlib.Path."):
-        GHPageServer(
-            directory=123,
-            port=8000,
-            base_path="",
-            strict=True,
-            no_cache=False,
-            threaded=True,
-        )
-
-
-def test_directory_not_found():
-    with pytest.raises(ValueError, match="`directory` does not exist."):
-        GHPageServer(
-            directory="__not_existing_dir__",
-            port=8000,
-            base_path="",
-            strict=True,
-            no_cache=False,
-            threaded=True,
-        )
-
-
-def test_directory_not_directory(tmp_path):
-    file_path = tmp_path / "file.txt"
-    file_path.write_text("data")
-
-    with pytest.raises(ValueError, match="`directory` must be a valid directory."):
-        GHPageServer(
-            directory=file_path,
-            port=8000,
-            base_path="",
-            strict=True,
-            no_cache=False,
-            threaded=True,
-        )
-
-
-def test_invalid_port_type(tmp_path):
-    with pytest.raises(ValueError, match="`port` must be int."):
-        GHPageServer(
-            directory=tmp_path,
-            port="8000",
-            base_path="",
-            strict=True,
-            no_cache=False,
-            threaded=True,
-        )
-
-
-def test_invalid_port_range(tmp_path):
-    with pytest.raises(ValueError, match="`port` must be between 1 and 65535."):
-        GHPageServer(
-            directory=tmp_path,
-            port=70000,
-            base_path="",
-            strict=True,
-            no_cache=False,
-            threaded=True,
-        )
-
-
-def test_invalid_base_path_type(tmp_path):
-    with pytest.raises(ValueError, match="`base_path` must be str."):
-        GHPageServer(
-            directory=tmp_path,
-            port=8000,
-            base_path=123,
-            strict=True,
-            no_cache=False,
-            threaded=True,
-        )
-
-
-def test_invalid_base_path_format(tmp_path):
-    with pytest.raises(ValueError, match="`base_path` must start with '/' or be empty."):
-        GHPageServer(
-            directory=tmp_path,
-            port=8000,
-            base_path="docs",
-            strict=True,
-            no_cache=False,
-            threaded=True,
-        )
-
-
-def test_invalid_strict_type(tmp_path):
-    with pytest.raises(ValueError, match="`strict` must be bool."):
-        GHPageServer(
-            directory=tmp_path,
-            port=8000,
-            base_path="",
-            strict="yes",
-            no_cache=False,
-            threaded=True,
-        )
-
-
-def test_invalid_no_cache_type(tmp_path):
-    with pytest.raises(ValueError, match="`no_cache` must be bool."):
-        GHPageServer(
-            directory=tmp_path,
-            port=8000,
-            base_path="",
-            strict=True,
-            no_cache="false",
-            threaded=True,
-        )
-
-
-def test_invalid_threaded_type(tmp_path):
-    with pytest.raises(ValueError, match="`threaded` must be bool."):
-        GHPageServer(
-            directory=tmp_path,
-            port=8000,
-            base_path="",
-            strict=True,
-            no_cache=False,
-            threaded="true",
-        )