Metadata-Version: 2.4
Name: pyservercheck
Version: 0.1.1
Summary: Check a server URL from Python using a bundled Node.js script
Author-email: Japhason <Japhason@proton.me>
License-Expression: MIT
Keywords: server,status,healthcheck,http,monitoring
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# pyservercheck

A small Python helper that checks server status. Use it when a project
needs a JavaScript step (for example a connectivity or status check)

## Requirements

- Python 3.9 or newer
- Node.js on `PATH` (`node` must be available)

No extra Python dependencies are required.

## Installation

From a local checkout:

```bash
pip install .
```

Editable install:

```bash
pip install -e .
```

The package data includes `pyservercheck/js/*.js`. After install you can import the
library from any working directory.

## Quick start

```python
from pyservercheck import run_js

run_js()
```


If the script file itself is missing from the install tree, it raises
`FileNotFoundError` naming the expected path.

## Bundled script

It performs an HTTP GET and prints
one JSON object to stdout, for example:

```json
{"url": "https://example.com", "statusCode": 200, "ok": true}
```

On failure it prints:

```json
{"url": "https://example.com", "ok": false, "error": "..."}
```

The request uses an 8 second timeout. The default URL is `https://example.com`.

## Configuration

| Variable      | Default                 | Meaning                                      |
|---------------|-------------------------|----------------------------------------------|
| `STATUS_URL`  | `https://example.com`   | URL passed to the bundled status script      |

Example:

```bash
set STATUS_URL=https://example.com
python -c "from pyservercheck import run_js; run_js()"
```

On Unix-like shells:

```bash
STATUS_URL=https://example.com python -c "from pyservercheck import run_js; run_js()"
```

## Public API

| Name     | Description                                      |
|----------|--------------------------------------------------|
| `run_js` | Run the bundled `main.js` with Node.js           |

```python
from pyservercheck import run_js
```

That is the only public entry point (`__all__ = ["run_js"]`).

## What happens at install time

pyservercheck uses a standard setuptools `cmdclass` so a source or editable install
can confirm that Node.js can execute the bundled script.

- `pip install .` / `pip install -e .` — after files are copied, the build
  runs `run_js()` once. If Node is not available, the install still succeeds
  and a note is printed to stderr.
- Wheel install — a `.pth` file is included so the same check can run once
  the first time that Python starts with this environment. A marker file
  (`.main_js_ran`) is written beside the package so the check does not repeat.

You can always call `run_js()` yourself later; install-time execution is only
a convenience so a fresh environment is verified early.

## Project layout

```
pyservercheck/
  __init__.py      Public export of run_js
  runtime.py       Locates main.js and starts Node
  js/main.js       Bundled status-check script
  _setup_cmd.py    setuptools build / develop helpers
  _hooks.py        One-time post-install check
```

## Troubleshooting

**`FileNotFoundError` about Node.js**  
Install Node.js and confirm `node --version` works in the same terminal you
use for Python.

**`FileNotFoundError` about `main.js`**  
Reinstall the package so package data is included (`include-package-data` is
enabled in `pyproject.toml`).

**The status script reports `"ok": false`**  
Check network access and, if you set `STATUS_URL`, that the host accepts a
simple GET.

## Development

```bash
pip install -e .
python -c "from pyservercheck import run_js; run_js()"
```

Python 3.9+ is declared in `pyproject.toml`. The build backend is setuptools
77 or newer.

## License

MIT. See `LICENSE`.
