Merge pull request #2 from PlasmaFAIR/release-prep

Release Prep

.github/workflows/build_publish.yml

@@ -0,0 +1,49 @@
+name: Build/publish Python Package
+
+on: push
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+      - name: Build package
+        run: |
+          python -m build --sdist --wheel
+      - name: Check package
+        run: |
+          python -m twine check dist/*
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    if: startsWith(github.ref, 'refs/tags/')  # only publish to PyPI on tag pushes
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+      url: https://pypi.org/p/epydeck
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

CITATION.cff

@@ -0,0 +1,17 @@
+cff-version: 1.2.0
+title: >-
+  epydeck - An EPOCH plasma PIC code input file (deck)
+  reader/writer
+message: 'If you use this software, please cite it using the metadata from this file.'
+type: software
+authors:
+  - family-names: Hill
+    given-names: Peter
+    orcid: 'https://orcid.org/0000-0003-3092-1858'
+    affiliation: University of York
+  - family-names: Adams
+    given-names: Joel L.
+    orcid: 'https://orcid.org/0009-0005-4889-5231'
+    affiliation: University of York
+repository-code: 'https://github.com/PlasmaFAIR/epydeck'
+date-released: '2024-04-22'

README.md

@@ -1,10 +1,72 @@
 # epydeck
 
-An EPOCH input file ("deck") reader/writer.
+An EPOCH plasma PIC code input file (deck) reader/writer.
 
-Plain numbers and bools are converted directly, everything else is
-represented as a string. Note that floating point numbers may have
-their exact form changed.
+> [!IMPORTANT]
+> Plain numbers and bools are converted directly, everything else is
+> represented as a string. Note that floating point numbers may have
+> their exact form changed.
+
+## Installation
+
+Install from PyPI with:
+
+```bash
+pip install epydeck
+```
+
+or from local checkout:
+
+```bash
+git clone https://github.com/PlasmaFAIR/epydeck.git
+cd epydeck
+pip install .
+```
+
+We recommend switching to [uv](https://docs.astral.sh/uv/) to manage packages.
+
+## Usage
+
+The interface follows the standard Python
+[`json`](https://docs.python.org/3/library/json.html) module:
+
+- `epydeck.load` to read from a `file` object
+- `epydeck.loads` to read from an existing string
+- `epydeck.dump` to write to a `file` object
+- `epydeck.dumps` to write to a string
+
+```python
+import epydeck
+
+# Read from a file with `epydeck.load`
+with open(filename) as f:
+    deck = epydeck.load(f)
+
+print(deck.keys())
+# dict_keys(['control', 'boundaries', 'constant', 'species', 'laser', 'output_global', 'output', 'dist_fn'])
+
+# Modify the deck as a usual python dict:
+deck["species"]["proton"]["charge"] = 2.0
+
+# Write to file
+with open(filename, "w") as f:
+    epydeck.dump(deck, f)
+
+print(epydeck.dumps(deck))
+# ...
+# begin:species
+#   name = proton
+#   charge = 2.0
+#   mass = 1836.2
+#   fraction = 0.5
+#   number_density = if((r gt ri) and (r lt ro), den_cone, 0.0)
+#   number_density = if((x gt xi) and (x lt xo) and (r lt ri), den_cone, number_density(proton))
+#   number_density = if(x gt xo, 0.0, number_density(proton))
+# end:species
+# ...
+```
+
+## Further Examples
 
 Reads from file into a standard Python `dict`. Repeated blocks, such
 as `species`, have an extra level of nesting using the block `name`.
@@ -81,60 +143,3 @@ is represented by the following `dict`:
   }
 }
 ```
-
-## Installation
-
-Currently just on Github, so either install from a local clone:
-
-```bash
-$ git clone [email protected]:PlasmaFAIR/epydeck.git
-$ cd epydeck
-$ pip install .
-```
-
-or directly from Github:
-
-```bash
-$ pip install [email protected]:PlasmaFAIR/epydeck.git
-```
-
-## Example
-
-The interface follows the standard Python
-[`json`](https://docs.python.org/3/library/json.html) module:
-
-- `epydeck.load` to read from a `file` object
-- `epydeck.loads` to read from an existing string
-- `epydeck.dump` to write to a `file` object
-- `epydeck.dumps` to write to a string
-
-```python
-import epydeck
-
-# Read from a file with `epydeck.load`
-with open(filename) as f:
-    deck = epydeck.load(f)
-
-print(deck.keys())
-# dict_keys(['control', 'boundaries', 'constant', 'species', 'laser', 'output_global', 'output', 'dist_fn'])
-
-# Modify the deck as a usual python dict:
-deck["species"]["proton"]["charge"] = 2.0
-
-# Write to file
-with open(filename, "w") as f:
-    epydeck.dump(deck, f)
-
-print(epydeck.dumps(deck))
-# ...
-# begin:species
-#   name = proton
-#   charge = 2.0
-#   mass = 1836.2
-#   fraction = 0.5
-#   number_density = if((r gt ri) and (r lt ro), den_cone, 0.0)
-#   number_density = if((x gt xi) and (x lt xo) and (r lt ri), den_cone, number_density(proton))
-#   number_density = if(x gt xo, 0.0, number_density(proton))
-# end:species
-# ...
-```

pyproject.toml

@@ -8,25 +8,25 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "epydeck"
+readme = "README.md"
 authors = [
-        {name = "Peter Hill", email = "[email protected]"},
-        {name = "Joel Adams", email = "[email protected]"}
+    { name = "Peter Hill", email = "[email protected]" },
+    { name = "Joel Adams", email = "[email protected]" },
 ]
-license = {text = "BSD"}
+license = { file = "LICENCE.md" }
 requires-python = ">=3.9"
 dynamic = ["version"]
+description = "An EPOCH plasma PIC code input file (deck) reader/writer."
 
 [project.optional-dependencies]
 docs = [
-     "sphinx >= 5.3",
-     "sphinx_autodoc_typehints >= 1.19",
-     "sphinx-book-theme >= 0.4.0rc1",
-     "sphinx-argparse-cli >= 1.10.0",
-     "sphinx-inline-tabs",
-]
-tests = [
-      "pytest >= 3.3.0",
+    "sphinx >= 5.3",
+    "sphinx_autodoc_typehints >= 1.19",
+    "sphinx-book-theme >= 0.4.0rc1",
+    "sphinx-argparse-cli >= 1.10.0",
+    "sphinx-inline-tabs",
 ]
+tests = ["pytest >= 3.3.0"]
 
 [tool.setuptools_scm]
 write_to = "src/epydeck/_version.py"