Skip to content

Commit 153f5ca

Browse files
Maximilian-WinterMaximilian-Winter
committed
Added detailed docs
1 parent cf253fb commit 153f5ca

115 files changed

Lines changed: 19661 additions & 1 deletion

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/settings.local.json‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,10 @@
33
"allow": [
44
"Bash(du:*)",
55
"Bash(grep:*)",
6-
"Bash(cd:*)"
6+
"Bash(cd:*)",
7+
"Bash(mkdir:*)",
8+
"Bash(pip install:*)",
9+
"Bash(mkdocs build:*)"
710
]
811
},
912
"outputStyle": "vajrayogini"

‎.github/workflows/docs.yml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
paths:
8+
- 'docs/**'
9+
- 'mkdocs.yml'
10+
- '.github/workflows/docs.yml'
11+
workflow_dispatch:
12+
13+
permissions:
14+
contents: read
15+
pages: write
16+
id-token: write
17+
18+
concurrency:
19+
group: "pages"
20+
cancel-in-progress: false
21+
22+
jobs:
23+
build:
24+
runs-on: ubuntu-latest
25+
steps:
26+
- name: Checkout repository
27+
uses: actions/checkout@v4
28+
29+
- name: Set up Python
30+
uses: actions/setup-python@v5
31+
with:
32+
python-version: '3.12'
33+
34+
- name: Install dependencies
35+
run: pip install -r requirements-docs.txt
36+
37+
- name: Build documentation
38+
run: mkdocs build --strict
39+
40+
- name: Upload artifact
41+
uses: actions/upload-pages-artifact@v3
42+
with:
43+
path: site/
44+
45+
deploy:
46+
needs: build
47+
runs-on: ubuntu-latest
48+
environment:
49+
name: github-pages
50+
url: ${{ steps.deployment.outputs.page_url }}
51+
steps:
52+
- name: Deploy to GitHub Pages
53+
id: deployment
54+
uses: actions/deploy-pages@v4

‎docs/about/changelog.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
title: Changelog
3+
---
4+
5+
# Changelog
6+
7+
All notable changes to Pytonium are documented on this page.
8+
9+
---
10+
11+
## v0.0.13 (February 2026)
12+
13+
This is a major feature release that adds multi-instance browser support, off-screen rendering with transparent windows, fullscreen mode, and numerous improvements to the build system and developer experience.
14+
15+
### Multi-Instance Browser
16+
17+
- **`create_browser(url, width, height)`** -- Create additional browser windows within the same process
18+
- **`close_browser(browser_id)`** -- Close a specific browser window by ID
19+
- **`get_browser_id()`** -- Get the browser ID of the current instance
20+
- **`is_cef_initialized()`** -- Check whether the CEF runtime has been initialized
21+
- **`run_pytonium_multi_async(instances)`** -- Run multiple Pytonium instances concurrently with asyncio
22+
23+
### Off-Screen Rendering
24+
25+
- **`set_osr_mode(enabled)`** -- Enable off-screen rendering for transparent window support
26+
- Per-pixel alpha transparency via CEF's off-screen rendering pipeline
27+
- Win32 layered windows with `UpdateLayeredWindow` compositing
28+
29+
### Fullscreen Mode
30+
31+
- **`set_fullscreen(enabled)`** -- Enter or exit fullscreen mode programmatically
32+
- **`toggle_fullscreen()`** -- Toggle between fullscreen and windowed mode
33+
- **`is_fullscreen()`** -- Query the current fullscreen state
34+
- Win32 borderless fullscreen implementation with saved/restored window state
35+
36+
### Window Event Callbacks
37+
38+
- **`on_title_change(callback)`** -- Called when the page title changes
39+
- **`on_address_change(callback)`** -- Called when the URL changes
40+
- **`on_fullscreen_change(callback)`** -- Called when fullscreen state changes (e.g., HTML5 fullscreen API)
41+
42+
### Async Integration
43+
44+
- **`run_pytonium_async(instance)`** -- Run a single Pytonium instance within an asyncio event loop
45+
- **`run_pytonium_multi_async(instances)`** -- Run multiple instances concurrently
46+
47+
### Window Control
48+
49+
- **`get_native_window_handle()`** -- Access the native HWND (Windows) or X11 window handle
50+
- **`set_window_position(x, y)`** / **`get_window_position()`** -- Control window position
51+
- **`set_window_size(w, h)`** / **`get_window_size()`** -- Control window size
52+
- **`minimize_window()`** / **`maximize_window()`** / **`restore_window()`** -- Window state control
53+
- **`drag_window()`** -- Initiate a native window drag operation
54+
- **`set_frameless_window(enabled)`** -- Remove native window chrome for custom titlebar designs
55+
56+
### Custom Schemes and MIME Types
57+
58+
- **`add_custom_scheme(name, path)`** -- Register custom URL protocols for local file serving
59+
- **`add_mime_type_mapping(extension, mime_type)`** -- Map file extensions to MIME types for custom schemes
60+
61+
### TypeScript Definitions
62+
63+
- **`generate_typescript_definitions(path)`** -- Auto-generate `.d.ts` files for bound Python functions
64+
65+
### Developer Experience
66+
67+
- GIL-safe callbacks throughout the Cython bridge (`with gil` + try/except on all 6 callback types)
68+
- JavaScript string injection hardening via `EscapeJsString`
69+
- Promise timeout and cleanup for bound function calls
70+
- Comprehensive type stubs (`.pyi`) for IDE auto-completion
71+
- Input validation and docstrings on all public methods
72+
- Mutable default argument fixes
73+
74+
### Platform Improvements
75+
76+
- DPI awareness on Windows (per-monitor DPI support)
77+
- Unicode path support on Windows (`GetModuleFileNameW`)
78+
- Atomic singleton pattern for CEF initialization
79+
- `RemoveState` guard for safe state cleanup
80+
- Cross-platform build system improvements (`prepare_build.py` script)
81+
82+
### Build System
83+
84+
- **`prepare_build.py`** -- Unified build preparation script with `--platform`, `--dry-run`, `--verbose`, and skip options
85+
- CMake paths cleaned up to use `${CMAKE_SOURCE_DIR}/`
86+
- Automated subprocess copy and CEF binary staging
87+
- Linux `.so` symbol stripping for smaller wheel size
88+
89+
### Supported Platforms
90+
91+
- Windows 11 (x86_64)
92+
- Linux with X11 (x86_64)
93+
- Python 3.10+
94+
95+
---
96+
97+
## Previous Versions
98+
99+
Pytonium was in early development prior to v0.0.13. The project history is available in the [git log](https://github.com/Maximilian-Winter/pytonium/commits/master).

‎docs/about/contributing.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
---
2+
title: Contributing
3+
---
4+
5+
# Contributing
6+
7+
Thank you for your interest in contributing to Pytonium. This page covers how to report bugs, set up a development environment, and submit changes.
8+
9+
---
10+
11+
## Reporting Bugs
12+
13+
If you encounter a bug, please open an issue on the [GitHub Issues](https://github.com/Maximilian-Winter/pytonium/issues) page with the following information:
14+
15+
!!! info "What to include in a bug report"
16+
- **Operating system and version** (e.g., Windows 11 23H2, Ubuntu 24.04)
17+
- **Python version** (e.g., Python 3.10.12)
18+
- **Pytonium version** (e.g., 0.0.13)
19+
- **Steps to reproduce** the issue
20+
- **Expected behavior** vs. **actual behavior**
21+
- **Error messages or stack traces** (if applicable)
22+
- **Minimal code example** that reproduces the problem
23+
24+
A minimal reproduction makes it much easier to diagnose and fix the issue.
25+
26+
---
27+
28+
## Feature Requests
29+
30+
Feature requests are welcome. Open a [GitHub Issue](https://github.com/Maximilian-Winter/pytonium/issues) with the `enhancement` label and describe:
31+
32+
- What you want to achieve
33+
- Why existing features do not meet your needs
34+
- Any ideas for how the feature could work
35+
36+
---
37+
38+
## Development Setup
39+
40+
### 1. Fork and Clone
41+
42+
Fork the repository on GitHub, then clone your fork:
43+
44+
```bash
45+
git clone https://github.com/YOUR-USERNAME/pytonium.git
46+
cd pytonium
47+
```
48+
49+
### 2. Create a Virtual Environment
50+
51+
=== "Windows"
52+
53+
```bash
54+
python -m venv .venv
55+
.venv\Scripts\activate
56+
pip install --upgrade pip
57+
pip install build scikit-build cmake ninja Cython
58+
```
59+
60+
=== "Linux"
61+
62+
```bash
63+
python3 -m venv .venv
64+
source .venv/bin/activate
65+
pip install --upgrade pip
66+
pip install build scikit-build cmake ninja Cython
67+
```
68+
69+
### 3. Build from Source
70+
71+
Follow the [Build Guide](../building/build-guide.md) to build and install Pytonium from source. This involves:
72+
73+
1. Building the C++ subprocess
74+
2. Running the prepare build script
75+
3. Building the Python wheel
76+
4. Installing the wheel
77+
78+
### 4. Run Tests
79+
80+
```bash
81+
python -m pytest tests/
82+
```
83+
84+
---
85+
86+
## Pull Request Guidelines
87+
88+
### Before Submitting
89+
90+
1. **Create a branch** from `master` for your changes:
91+
92+
```bash
93+
git checkout -b my-feature-branch
94+
```
95+
96+
2. **Make your changes** in focused, logical commits.
97+
98+
3. **Test your changes** by running the existing test suite and adding new tests if applicable.
99+
100+
4. **Verify the build** completes successfully on your platform.
101+
102+
### Submitting
103+
104+
1. Push your branch to your fork:
105+
106+
```bash
107+
git push origin my-feature-branch
108+
```
109+
110+
2. Open a Pull Request against the `master` branch of the main repository.
111+
112+
3. In the PR description, explain:
113+
- **What** the change does
114+
- **Why** the change is needed
115+
- **How** you tested it
116+
- Any **breaking changes** or **migration steps** required
117+
118+
!!! warning "Large Changes"
119+
For significant changes (new features, architectural changes, API modifications), consider opening an issue first to discuss the approach before writing code.
120+
121+
---
122+
123+
## Code Style
124+
125+
### C++ (src/pytonium_library/, src/pytonium_subprocess/)
126+
127+
- **Standard**: C++20
128+
- **Naming**: PascalCase for classes and methods, camelCase for local variables
129+
- **Formatting**: 4-space indentation
130+
- **Definitions**: Use `add_compile_definitions(NOMINMAX WIN32_LEAN_AND_MEAN)` on Windows
131+
- **Window API**: Use the `W` variants (e.g., `GetWindowLongPtrW`, `GetModuleFileNameW`) for Unicode support
132+
- **Pointer size**: Use `GetWindowLongPtrW`/`SetWindowLongPtrW` (not `GetWindowLongW`) for 64-bit safety
133+
134+
### Cython (src/pytonium_python_framework/Pytonium/src/pytonium.pyx)
135+
136+
- All callbacks must use `with gil` and wrap the body in `try/except`
137+
- Keep the `.pxd` declarations in sync with the C++ header
138+
- Update the `.pyi` stub file when adding or changing public methods
139+
140+
### Python
141+
142+
- **Standard**: PEP 8
143+
- **Type hints**: Required on all public functions and methods
144+
- **Docstrings**: Required on all public functions and methods
145+
- **Default arguments**: Do not use mutable default arguments (lists, dicts)
146+
147+
### Type Stubs (.pyi)
148+
149+
The type stubs at `src/pytonium_python_framework/Pytonium/pytonium.pyi` are **hand-maintained** (not auto-generated). If you add or modify a public method in the Cython bridge, update the stubs accordingly.
150+
151+
---
152+
153+
## Project Structure
154+
155+
```
156+
pytonium/
157+
src/
158+
pytonium_library/ # C++ core library
159+
pytonium_subprocess/ # C++ subprocess for CEF multi-process
160+
pytonium_python_framework/
161+
Pytonium/
162+
src/
163+
pytonium.pyx # Cython bridge
164+
pytonium_library.pxd # C++ declarations
165+
__init__.py # Package init
166+
pytonium.pyi # Type stubs
167+
setup.py # scikit-build setup
168+
tests/ # Test suite
169+
building_pythonium_core/ # Build preparation scripts
170+
docs/ # MkDocs documentation
171+
cef-binaries-windows/ # CEF binaries (not in git)
172+
cef-binaries-linux/ # CEF binaries (not in git)
173+
```
174+
175+
---
176+
177+
## Areas Where Help is Appreciated
178+
179+
- **macOS support** -- Pytonium does not yet support macOS
180+
- **Wayland support** -- Currently X11 only on Linux
181+
- **Documentation improvements** -- Corrections, clarifications, additional examples
182+
- **Test coverage** -- Additional unit and integration tests
183+
- **Bug fixes** -- See the [open issues](https://github.com/Maximilian-Winter/pytonium/issues)
184+
185+
---
186+
187+
## License
188+
189+
By contributing to Pytonium, you agree that your contributions will be licensed under the [MIT License](license.md), the same license that covers the project.

0 commit comments

Comments
 (0)