README, CONTRIBUTING: improve the description of the project
- ID
dab5991- date
2026-07-16 20:24:11+00:00- author
Alex Chan <alex@alexwlchan.net>- parent
b2c9a54- message
README, CONTRIBUTING: improve the description of the project- changed files
2 files, 73 additions, 63 deletions
Changed files
CONTRIBUTING.md (1281 → 923)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9f37a1b..c0af775 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,55 +2,36 @@
You can set up a local development environment by cloning the repo and installing dependencies:
-```shell
-git clone https://github.com/alexwlchan/javascript-data-files.git
-cd javascript-data-files
-python3 -m venv .venv
-source .venv/bin/activate
-pip install -e .
+```console
+$ git clone git://alexwlchan.net/projects/javascript-data-files.git
+$ cd chives
+$ python3 -m venv .venv
+$ source .venv/bin/activate
+$ pip install -e .
```
-If you want to run tests, install the dev dependencies and run the tests:
+If you want to run tests, install the dev dependencies and run the `run_javascript_data_files_tests.sh` script:
-```shell
-# Activate the virtualenv and install dev dependencies
-source .venv/bin/activate
-pip install -r dev_requirements.txt
+```console
+$ # Activate the virtualenv
+$ source .venv/bin/activate
-# Check formatting
-ruff check .
-ruff format --check .
+$ # Install dev dependencies
+$ pip install -r dev_requirements.txt
-# Check docstrings
-interrogate -vv
-
-# Check types
-mypy src tests
-
-# Run tests
-coverage run -m pytest tests
-coverage report
+$ # Run tests
+$ bash scripts/run_javascript_data_files_tests.sh
```
To make changes:
1. Create a new branch
-2. Push your changes to GitHub
-3. Open a pull request
-4. Fix any issues flagged by GitHub Actions (including tests, code linting, and type checking)
-6. Merge it!
-
-To create a new version on PyPI:
-
-1. Update the version in `src/javascript_data_files/__init__.py`
-2. Add release notes in `CHANGELOG.md` and push a new tag to GitHub
-3. Deploy the release using twine:
+2. Work on your changes in that branch, iterating until your change works as expected and the tests pass
+3. Commit your changes
+4. Export your changes to a patch file:
```console
- $ python3 -m build
- $ python3 -m twine upload dist/* --username=__token__
+ $ git format-patch <branch_name> --stdout
```
- You will need [a PyPI API token](https://pypi.org/help/#apitoken) to publish packages.
-
-
+5. Email me your patch file for review.
README.md (1984 → 3235)
diff --git a/README.md b/README.md
index 113a02c..04eb257 100644
--- a/README.md
+++ b/README.md
@@ -2,59 +2,88 @@
This is a collection of Python functions for manipulating JavaScript "data files" -- that is, JavaScript files that define a single variable with a JSON value.
-This is an example of a JavaScript data file:
+Think of this as the Python `json` module, but built specifically for JavaScript files like this:
```javascript
const shape = { "sides": 5, "colour": "red" };
```
-Think of this module as the JSON module, but for JavaScript files.
+## Why not use JSON files?
+
+If you open a local HTML file directly from your disk (`file://...`), browsers block you from loading local `.json` files via `fetch()` or `XMLHttpRequest` due to CORS (Cross-Origin Resource Sharing) restrictions.
+
+However, you *can* load a local JavaScript file using a standard script tag:
+
+```html
+<script src="file:///Users/alexwlchan/repos/javascript-data-files/data.js"></script>
+```
+
+I build and maintain a lot of local static websites and offline HTML viewers. Storing my metadata in JavaScript files rather than JSON is the only way to load external data into these local files without the hassle of running a local web server.
+
+I have [a lot of local static websites][static-websites-howto] that I use for my local media archives.
+Storing my metadata in JavaScript files rather than JSON allows me to load metadata in an HTML file without the hassle of running a local web server.
+
+The minor annoyance of writing to `.js` files instead of pure `.json` is easily offset by the convenience of just double-clicking an HTML file to open it.
+This library bridges the gap, letting my Python backend scripts easily read, write, and update those JavaScript data files.
-These data files are meant to be both human- and machine-readable.
+[static-websites-howto]: https://alexwlchan.net/2025/mildly-dynamic-websites/
## Usage
-If you install `javascript-data-files`:
+```python
+from javascript_data_files import (
+ read_js,
+ write_js,
+ append_to_js_array,
+ append_to_js_object,
+ read_typed_js,
+)
+```
+
+The library provides four core functions:
-* You can read a JavaScript file with `read_js(path, varname)`
-* You can write a JavaScript file with `write_js(path, value, varname)`
-* You can append an item to a JavaScript array with `append_to_js_array(path, value)`
-* You can append a key-value pair to a JavaScript object with `append_to_js_object(path, key, value)`
+- **Read:** Get a file's value with `read_js(path, varname)`
+- **Write:** Create or overwrite a file with `write_js(path, value, varname)`
+- **Append to array:** Add an item to a JavaScript array with `append_to_js_array(path, value)`
+- **Append to object:** Add a key-value pair to a JavaScript object with `append_to_js_object(path, key, value)`
-If you install `javascript-data-files[typed]`:
+If you install the `typed` extra, you can validate your JavaScript data against a Python type or Pydantic model:
-* You can read a JavaScript file and validate it matches a particular Python type with `read_typed_js(path, varname, model)`.
+- **Typed read:** `read_typed_js(path, varname, model)`
## Installation
You have two options:
-1. Copy the file `src/javascript` folder into your project.
- You probably want to copy the tests as well.
+1. Copy the `src/javascript` directory and its tests directly into your project.
+ Just keep a link back here!
-2. Install the package using pip:
+2. Install via pip:
```console
$ pip install javascript-data-files
```
+
+ To include type-checking capabilities:
+
+ ```console
+ $ pip install javascript-data-files[typed]
+ ```
-## Why not use JSON files?
-
-If you've opening an HTML file from disk, you can load data from a local JavaScript file, for example:
+## Versioning and stability
-```html
-<script src="file://users/alexwlchan/repos/javascript-data-files/data.js"></script>
-```
+This library uses [semantic versioning][semver].
+Patch and minor versions will not contain breaking changes.
-This is the only way to load data from an external file from an HTML file you've opened locally -- you can't do this with a JSON file, for example.
+In practice, the library is unlikely to change much in future versions – it does one specific job, and it does it well.
-I have a lot of HTML files and local sites I build with an HTML viewer and metadata in a JavaScript file.
-The convenience of this approach outweighs the mild annoyance of having to store data in JavaScript, not JSON.
+[semver]: https://semver.org/
-## Development
+## Development and feedback
-If you want to make changes to the library, there are instructions in [CONTRIBUTING.md](./CONTRIBUTING.md).
+Want to contribute or tweak something?
+Check out [CONTRIBUTING.md](./CONTRIBUTING.md) for local setup instructions.
## License
-MIT.
+This project is shared under the [MIT license](./LICENSE).