pyservercheck

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:

pip install .

Editable install:

pip install -e .

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

Quick start

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:

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

On failure it prints:

{"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:

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

On Unix-like shells:

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

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

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.