Metadata-Version: 2.4
Name: phasma
Version: 0.2.0
Author-email: Mohammad Raziei <mohammadraziei1375@gmail.com>
License: MIT License
        
        Copyright (c) 2023-present Mohammad Raziei mohammadraziei1375@gmail.com
        
        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: Source, https://github.com/mohammadraziei/phasma
Project-URL: Issues, https://github.com/mohammadraziei/phasma/issues
Project-URL: Documentation, https://mohammadraziei.github.io/phasma
Platform: Linux
Platform: Windows
Platform: macOS
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file
Dynamic: platform

# Phasma: PhantomJS Driver for Python

<div align="center">
<img src="https://github.com/MohammadRaziei/phasma/raw/master/docs/images/phasma.jpg" width="30%" style="min-width: 200px;" alt="Phasma Logo" />
</div>

**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:

```bash
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:

```bash
git clone https://github.com/MohammadRaziei/phantomjs-driver.git
cd phantomjs-driver
pip install -e .
```

## Quick Start

### Using the Python API

```python
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

```bash
# Show driver version
python -m phasma driver --version

# Show driver executable path
python -m phasma driver --path

# Download the driver
python -m phasma driver download

# 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)`
Downloads the PhantomJS driver for the given OS and architecture. If no arguments are provided, it auto‑detects the current platform.

### `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:

```python
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

```python
# 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:

```bash
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.

1. Fork the repository.
2. Create a feature branch.
3. Make your changes and add tests.
4. Ensure all tests pass.
5. Submit a pull request.

## License

Phasma is distributed under the MIT License. See the [LICENSE](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.
