ghps 0.2__tar.gz → 0.3__tar.gz

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

@@ -5,6 +5,15 @@ 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.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 +27,8 @@ 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.3...dev
+[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.3}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: ghps
-Version: 0.2
+Version: 0.3
 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.3
 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.3](https://github.com/sepandhaghighi/ghps/archive/v0.3.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.3`						
 
 
 ## 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,15 @@ 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.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 +238,8 @@ 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.3...dev
+[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.3}/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.3](https://github.com/sepandhaghighi/ghps/archive/v0.3.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.3`						
 
 
 ## 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.3}/SECURITY.md

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

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

@@ -7,6 +7,16 @@ from pathlib import Path
 from .params import GHPS_VERSION
 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."""
@@ -57,29 +67,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 ValueError as e:
+        _print_cli_error(str(e))
+    except Exception as e:
+        _print_cli_error(f"Unexpected error: {e}")

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

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 """ghps params."""
 
-GHPS_VERSION = "0.2"
+GHPS_VERSION = "0.3"
 
 INVALID_DIRECTORY_TYPE_ERROR = "`directory` must be str or pathlib.Path."
 DIRECTORY_NOT_FOUND_ERROR = "`directory` does not exist."
@@ -16,3 +16,4 @@ 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."

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

@@ -3,6 +3,7 @@
 
 import http.server
 import socketserver
+import webbrowser
 from typing import Optional, Any
 from pathlib import Path
 from urllib.parse import unquote
@@ -17,6 +18,7 @@ from .params import (
     INVALID_STRICT_TYPE_ERROR,
     INVALID_NO_CACHE_TYPE_ERROR,
     INVALID_THREADED_TYPE_ERROR,
+    INVALID_AUTO_OPEN_TYPE_ERROR
 )
 
 
@@ -27,6 +29,7 @@ def _validate_inputs(
     strict: Any,
     no_cache: Any,
     threaded: Any,
+    auto_open: Any,
 ):
     """
     Validate GHPageServer inputs.
@@ -37,6 +40,7 @@ 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)
@@ -51,7 +55,7 @@ def _validate_inputs(
     if not isinstance(port, int):
         raise ValueError(INVALID_PORT_TYPE_ERROR)
 
-    if not (1 <= port <= 65535):
+    if not (0 <= port <= 65535):
         raise ValueError(INVALID_PORT_RANGE_ERROR)
 
     if not isinstance(base_path, str):
@@ -69,6 +73,9 @@ def _validate_inputs(
     if not isinstance(threaded, bool):
         raise ValueError(INVALID_THREADED_TYPE_ERROR)
 
+    if not isinstance(auto_open, bool):
+        raise ValueError(INVALID_AUTO_OPEN_TYPE_ERROR)
+
 
 class _GHRequestHandler(http.server.SimpleHTTPRequestHandler):
     """Custom HTTP request handler for serving static files with optional base path stripping, strict routing, custom 404 page support, and cache control headers."""
@@ -178,6 +185,7 @@ class GHPageServer:
         strict: bool = True,
         no_cache: bool = False,
         threaded: bool = True,
+        auto_open: bool = False,
     ):
         """
         Initialize the server.
@@ -188,6 +196,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 +205,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 +213,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:
@@ -223,12 +234,18 @@ 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}")
+        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.3}/ghps.egg-info/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: ghps
-Version: 0.2
+Version: 0.3
 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.3
 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.3](https://github.com/sepandhaghighi/ghps/archive/v0.3.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.3`						
 
 
 ## 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,15 @@ 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.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 +238,8 @@ 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.3...dev
+[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.3}/setup.py

@@ -32,7 +32,7 @@ def read_description() -> str:
 setup(
     name='ghps',
     packages=['ghps'],
-    version='0.2',
+    version='0.3',
     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.3',
     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.3}/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.2 → ghps-0.3}/tests/test_error.py

@@ -1,5 +1,6 @@
 # -*- coding: utf-8 -*-
 import pytest
+from unittest.mock import patch
 from ghps import GHPageServer
 
 
@@ -124,3 +125,36 @@ def test_invalid_threaded_type(tmp_path):
             no_cache=False,
             threaded="true",
         )
+
+
+def test_invalid_auto_open_type(tmp_path):
+    with pytest.raises(ValueError, 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
+    )

{ghps-0.2 → ghps-0.3}/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