No project description provided
Project description
Phasma: PhantomJS Driver for Python
Phasma is a Python library that provides a clean, high-level interface to PhantomJS, enabling headless browser automation, web page rendering, and JavaScript execution. It simplifies the process of downloading, managing, and interacting with PhantomJS, making it ideal for web scraping, screenshot capture, and automated testing.
Features
- Bundled Driver: PhantomJS driver is included in the package (Windows, macOS, Linux). No separate download needed.
- Page Rendering: Render HTML files, strings, and remote URLs with JavaScript support.
- JavaScript Execution: Run arbitrary JavaScript code in a PhantomJS context.
- CLI Interface: Command-line tools for quick operations.
- Cross‑Platform: Works on Windows, Linux, and macOS.
- Lightweight: Minimal dependencies, focused on simplicity and reliability.
Installation
Install from PyPI:
pip install phasma
The package includes the PhantomJS driver for Windows, macOS, and Linux (both 32‑bit and 64‑bit). No separate download is required.
Or install from source:
git clone https://github.com/MohammadRaziei/phantomjs-driver.git
cd phantomjs-driver
pip install -e .
Quick Start
Using the Python API
from phasma import render_page, render_url, execjs
# The PhantomJS driver is bundled with the package, ready to use.
# Render an HTML file
html = render_page("path/to/page.html")
print(html)
# Render a URL
content = render_url("https://example.com", wait_time=2000)
print(content[:500]) # first 500 characters
# Execute JavaScript
output = execjs("console.log('Hello from PhantomJS');")
print(output)
Using the Command Line
# Show driver version
python -m phasma driver --version
# Show driver executable path
python -m phasma driver --path
# Download the driver (use --force to re-download)
python -m phasma driver download
python -m phasma driver download --force
# Execute PhantomJS directly with arguments
python -m phasma driver exec --version
python -m phasma driver exec script.js
python -m phasma driver exec --cwd /path/to/working/dir script.js
python -m phasma driver exec --ssl --timeout 10 script.js
python -m phasma driver exec --no-ssl --capture-output script.js
# Render an HTML file
python -m phasma render-page tests/data/test_page.html
# Render a URL
python -m phasma render-url https://example.com --wait 2000
# Execute JavaScript
python -m phasma execjs "console.log('Hello');"
API Reference
download_driver(os_name=None, arch=None, force=False)
Downloads the PhantomJS driver for the given OS and architecture. If no arguments are provided, it auto‑detects the current platform. Set force=True to re‑download even if the driver already exists.
Driver.exec(args, *, capture_output=False, timeout=30, check=False, ssl=False, env=None, cwd=None, **kwargs)
Executes PhantomJS with the given arguments. Returns a subprocess.CompletedProcess instance.
args: Command line arguments as a string or sequence of strings.capture_output: IfTrue, capture stdout and stderr.timeout: Timeout in seconds.check: IfTrue, raiseCalledProcessErroron non‑zero exit code.ssl: IfFalse(default), setOPENSSL_CONFenvironment variable to empty string (disables SSL verification).env: Optional environment variables dictionary for subprocess.cwd: Optional working directory for subprocess.
render_page(page, output=None, viewport_size="1024x768", wait_time=100, **kwargs)
Renders an HTML page (file path or HTML string) and returns the rendered HTML. Optionally saves the output to a file.
render_url(url, output=None, viewport_size="1024x768", wait_time=0, **kwargs)
Renders a remote URL and returns the rendered HTML. Optionally saves the output to a file.
execjs(script, args=None, **kwargs)
Executes JavaScript code in a PhantomJS context and returns the stdout.
Advanced Usage
Rendering Dynamic JavaScript Content
Phasma can render pages that modify their DOM with JavaScript:
from phasma import render_page
html_with_js = """
<html>
<body>
<div id="container">Initial</div>
<script>
document.getElementById('container').innerHTML = '<h2>Generated by JS</h2>';
</script>
</body>
</html>
"""
rendered = render_page(html_with_js, wait_time=500)
assert "<h2>Generated by JS</h2>" in rendered
Custom Viewport and Wait Time
# Render with a custom viewport and longer wait
rendered = render_page(
"page.html",
viewport_size="1920x1080",
wait_time=2000,
output="screenshot.html"
)
Testing
Run the test suite with pytest:
pytest tests/
All core functionality is covered by unit tests, including page rendering, URL fetching, and JavaScript execution.
Contributing
Contributions are welcome! Please open an issue or submit a pull request on GitHub.
- Fork the repository.
- Create a feature branch.
- Make your changes and add tests.
- Ensure all tests pass.
- Submit a pull request.
License
Phasma is distributed under the MIT License. See the LICENSE file for details.
Acknowledgments
- PhantomJS team for the amazing headless browser.
- The Python community for excellent tooling and support.
Phasma – Making PhantomJS easy for Python developers.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file phasma-0.3.0-py3-none-win_amd64.whl.
File metadata
- Download URL: phasma-0.3.0-py3-none-win_amd64.whl
- Upload date:
- Size: 18.2 MB
- Tags: Python 3, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
200e34dd5c46ad10fe2c3c853abaa210464e831a4639f3dda7d1af53437d0f36
|
|
| MD5 |
a88fe1f5c9e836cceb421bea7b2875ee
|
|
| BLAKE2b-256 |
efa1006c1278c326e9254aeba1d4858e8ad8a922b218283c6c1e5f6848cdf0ad
|
File details
Details for the file phasma-0.3.0-py3-none-manylinux_2_17_x86_64.whl.
File metadata
- Download URL: phasma-0.3.0-py3-none-manylinux_2_17_x86_64.whl
- Upload date:
- Size: 26.2 MB
- Tags: Python 3, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1d3f68f950f3f95d97933659bfea324bf9718c45f398f72cd46d418183f2ec4c
|
|
| MD5 |
f634b7c788fb51d7c25e2e90af90137d
|
|
| BLAKE2b-256 |
e5256e61114453e723429fdedaad80939ae944cb8d0ad3357cfc2bf4861e3bf7
|
File details
Details for the file phasma-0.3.0-py3-none-manylinux_2_17_i686.whl.
File metadata
- Download URL: phasma-0.3.0-py3-none-manylinux_2_17_i686.whl
- Upload date:
- Size: 27.3 MB
- Tags: Python 3, manylinux: glibc 2.17+ i686
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4e18b393a7e07f73d8e0b1d692fafd2b8faeb4ee832415a8d9cc2b987a963f75
|
|
| MD5 |
13571087e138edebfb087441ef1a9c1b
|
|
| BLAKE2b-256 |
4ae42f9bb2ee77edf238f837a1b158e44ea27fb9f556a33edabf34707ee54e05
|
File details
Details for the file phasma-0.3.0-py3-none-macosx_10_9_x86_64.whl.
File metadata
- Download URL: phasma-0.3.0-py3-none-macosx_10_9_x86_64.whl
- Upload date:
- Size: 17.2 MB
- Tags: Python 3, macOS 10.9+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6a9ba690a940a6acf82ccbfeb4c6d172ca488e8bc08cdc7be8baf2dbd3ec9f1c
|
|
| MD5 |
b074609f8513c73e1ab480ce398c7b5e
|
|
| BLAKE2b-256 |
8ec5712ecc939cb6a25a4db813c13bc883e4b6e08a6eaeae09e6fb8020bc8d64
|
