Metadata-Version: 2.4
Name: scriptman
Version: 2.9.584
Summary: A powerful Python package for automation, script management, and workflow orchestration.
License: MIT License
         
         Copyright (c) 2024 Nelson Ombuya
         
         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.
License-File: LICENSE
Author: Nelson Ombuya
Author-email: developer@incognitouser.anonaddy.me
Requires-Python: >=3.12,<4.0
Classifier: License :: OSI Approved :: MIT License
Provides-Extra: api
Provides-Extra: cache
Provides-Extra: etl
Provides-Extra: pyodbc
Provides-Extra: selenium
Provides-Extra: sqlalchemy
Requires-Dist: dill (>=0.3.9) ; extra == "cache"
Requires-Dist: diskcache (>=5.6.3) ; extra == "cache"
Requires-Dist: fastapi (>=0.115.12) ; extra == "api"
Requires-Dist: filelock (>=3.16.1)
Requires-Dist: loguru (>=0.7.3)
Requires-Dist: pandas (>=2.2.3) ; extra == "etl"
Requires-Dist: pandas-stubs (>=2.2.3.241126) ; extra == "etl"
Requires-Dist: psutil (>=7.0.0,<8.0.0)
Requires-Dist: pydantic[email] (>=2.10.6) ; extra == "api"
Requires-Dist: pyodbc (>=5.2.0) ; extra == "pyodbc"
Requires-Dist: pyodbc (>=5.2.0) ; extra == "sqlalchemy"
Requires-Dist: requests (>=2.32.3) ; extra == "api"
Requires-Dist: requests (>=2.32.3) ; extra == "selenium"
Requires-Dist: selenium (>=4.28.1) ; extra == "selenium"
Requires-Dist: sqlalchemy (>=2.0.37) ; extra == "sqlalchemy"
Requires-Dist: tomlkit (>=0.13.2)
Requires-Dist: tqdm (>=4.67.1)
Requires-Dist: types-psutil (>=7.0.0.20250601,<8.0.0.0)
Requires-Dist: types-requests (>=2.32.0.20241016) ; extra == "api"
Requires-Dist: types-requests (>=2.32.0.20241016) ; extra == "selenium"
Requires-Dist: types-selenium (>=3.141.9) ; extra == "selenium"
Requires-Dist: types-tqdm (>=4.67.0.20241221)
Requires-Dist: uvicorn (>=0.34.0) ; extra == "api"
Requires-Dist: webdriver-manager (>=4.0.2) ; extra == "selenium"
Description-Content-Type: text/markdown

# Scriptman

Scriptman is a batteries-included Python automation toolkit that helps you build
web automation, ETL pipelines, and scheduled workflows with minimal ceremony.

## Features

- 🚀 **Selenium Automation** – Cross-platform browser automation with intelligent download handling
- 📊 **ETL Operations** – Pandas-powered Extract/Transform/Load helpers for CSV, JSON, and databases
- 🧠 **Task Manager & Services** – Cooperative services, multithreaded execution, and retry utilities
- ⏰ **Scheduling** – Interval, daily, and one-off triggers with decorator-friendly APIs
- 🗄️ **Database Support** – SQLAlchemy and pyodbc integrations out of the box
- ⚙️ **Configuration** – Flexible TOML configuration with sensible defaults
- 📚 **Documentation** – In-depth guides under [`scriptman/docs`](scriptman/docs)

## Quick Start

### Installation

```bash
pip install scriptman
```

### Hello Scriptman

```python
from datetime import timedelta

from scriptman import TaskManager, scheduler

manager = TaskManager()

# Register a cooperative service loop
def send_heartbeat() -> None: ...  # your implementation

@manager.service(name="heartbeat", autostart=True)
def heartbeat(ctx):
    while not ctx.should_stop:
        send_heartbeat()
        if not ctx.sleep(60):  # exit early if shutdown requested
            break

# Schedule a periodic task
@scheduler.schedule(trigger=scheduler.IntervalTrigger(timedelta(minutes=30)))
def sync_remote_data():
    ...  # your sync routine

if __name__ == "__main__":
    manager.start_service("heartbeat")
```

## Task Manager, Services & Scheduler

```python
from datetime import time

from scriptman import TaskManager, scheduler

manager = TaskManager()

@manager.service(name="report-generator", autostart=True)
def report_service(ctx):
    while not ctx.should_stop:
        generate_incremental_report()
        if not ctx.sleep(300):
            break

@manager.service(name="summary", autostart=False)
def summary_service(ctx):
    generate_summary()

@scheduler.schedule(trigger=scheduler.TimeOfDayTrigger(at=time(hour=21)))
def nightly_rollup() -> None:
    finalize_daily_metrics()

manager.start_service("report-generator")
```

The scheduler proxy (`scriptman.scheduler`) is always available, even before a
`TaskManager` is explicitly constructed, and the service proxy
(`scriptman.service_manager`) lets you introspect currently registered services.

## Selenium & Downloads

```python
from scriptman.powers.selenium import SeleniumInstance

selenium = SeleniumInstance()
selenium.driver.get("https://example.com")
selenium.interact_with_element("//button[@id='download']", mode="click")
downloaded_file = selenium.wait_for_downloads_to_finish("report.pdf")
print(f"Downloaded: {downloaded_file}")
```

Scriptman defaults to your system Downloads directory, automatically monitoring
Chrome’s default location and relocating finished downloads. Override it in
configuration if you need a custom path:

```toml
# scriptman.toml
[scriptman]
downloads_dir = "/path/to/custom/downloads"
```

## ETL & Data Pipelines

```python
from scriptman.powers.etl import ETL

etl = (
    ETL.from_db(prod_db, "SELECT * FROM sales")
    .transform(add_calculated_fields)
    .to_db(warehouse_db, "sales_fact", method="upsert")
)
```

Full ETL documentation—including architecture, examples, and API reference—lives
under [`scriptman/docs/powers/etl`](scriptman/docs/powers/etl).

## Configuration Snapshot

```toml
# scriptman.toml
[scriptman]
log_level = "INFO"
downloads_dir = "~/Downloads"

[scriptman.selenium]
headless = true
local_mode = true

[scriptman.tasks]
retries = 3
task_timeout = 30
```

## Documentation

Detailed guides and API references live in the [`scriptman/docs`](scriptman/docs)
directory. Start with the module READMEs (e.g. the ETL quick-start) and keep an
eye out for upcoming documentation on tasks, services, scheduler, Selenium, and
database helpers.

## License

This project is licensed under the MIT License—see the [LICENSE](LICENSE) file
for details.

