Fix for test.pypi.org

- use pyproject.toml to define project metadata and setuptools-specific configuration, removing the need for a setup.py file
- move sources in conventional src/ directory
- rework stubs so that they're visible downstream. PEP-561 doesn't support top-level .pyi files, so I made a dummy package instead `alsaaudio-stubs`

.github/workflows/docs.yml

@@ -2,7 +2,7 @@ on:
   workflow_dispatch:
   push:
     branches:
-      - main
+      - mttbernardini/chore/modern-packaging
 
 concurrency:
   group: "pages"

.github/workflows/release.yml

@@ -42,7 +42,8 @@ jobs:
   upload_pypi:
     needs: [build_wheels, build_sdist]
     runs-on: ubuntu-latest
-    environment: pypi
+    # TODO: set environment back to pypi after testing
+    environment: testpypi
     permissions:
       id-token: write
     steps:
@@ -53,3 +54,6 @@ jobs:
           path: dist
           merge-multiple: true
       - uses: pypa/gh-action-pypi-publish@release/v1
+        # TODO: delete below once workflow is proved functional
+        with:
+          repository-url: https://test.pypi.org/legacy/

README.md

@@ -46,9 +46,14 @@ First, get the sources and change to the source directory:
   $ cd pyalsaaudio
 ```
 
-Then, build and install:
+Then, build:
 ```
-  $ pip install .
+  $ python setup.py build
+```
+
+And install:
+```
+  $ sudo python setup.py install
 ```
 
 # Using the API
@@ -57,8 +62,8 @@ distribution; it is also online on [http://larsimmisch.github.io/pyalsaaudio/](h
 
 There are some example programs included with the source:
 
-* [playwav.py](./examples/playwav.py) plays back a wav file
+* [playwav.py](https://github.com/larsimmisch/pyalsaaudio/blob/master/playwav.py) plays back a wav file
-* [playbacktest.py](./examples/playbacktest.py) plays back raw sound data read from stdin
+* [playbacktest.py](https://github.com/larsimmisch/pyalsaaudio/blob/master/playbacktest.py) plays back raw sound data read from stdin
-* [recordtest.py](./examples/recordtest.py) captures sound from the microphone and writes
+* [recordtest.py](https://github.com/larsimmisch/pyalsaaudio/blob/master/recordtest.py) captures sound from the microphone and writes
 it raw to stdout.
-* [mixertest.py](./examples/mixertest.py) can be used to manipulate the mixers.
+* [mixertest.py](https://github.com/larsimmisch/pyalsaaudio/blob/master/mixertest.py) can be used to manipulate the mixers.

doc/README.md

@@ -1,18 +1,28 @@
 # Make a new release
 
-Create and push a tag naming the version (i.e. 0.11.1):
+Update the version in setup.py
 
-    git tag 0.11.1
+    pyalsa_version = '0.9.0'
-    git push origin 0.11.1
 
-This should trigger a build via a github actions and publish pre-built binaries to pypi.org 
+Commit and push the update.
+
+Create and push a tag naming the version (i.e. 0.9.0):
+
+    git tag 0.9.0
+    git push origin 0.9.0
+
+Create the package:
+
+    python3 setup.py sdist
+
+Upload the package
+
+    twine upload dist/*
+
+Don't forget to update the documentation.
 
 # Publish the documentation
 
-All commits to main should trigger a rebuild of the documentation.
-
-## Historical background
-
 The documentation is published through the `gh-pages` branch.
 
 To publish the documentation, you need to clone the `gh-pages` branch of this repository into

doc/libalsaaudio.rst

@@ -807,6 +807,9 @@ Play back the recording with::
 
    $ python playbacktest.py <filename>
 
+playbacktest.py accepts the commandline option
+ *-d <device>*.
+
 mixertest.py
 ~~~~~~~~~~~~
 

doc/pyalsaaudio.rst

@@ -77,7 +77,7 @@ Note: the wrappers link with the alsasound library (from the alsa-lib package)
 and need the ALSA headers for compilation.  Verify that you have
 /usr/lib/libasound.so and /usr/include/alsa (or similar paths) before building.
 
-*On Debian (and probably Ubuntu), install libasound2-dev.*
+*On Debian/Ubuntu, install libasound2-dev.*
 
 Naturally you also need to use a kernel with proper ALSA support. This is the
 default in Linux kernel 2.6 and later. If you are using kernel version 2.4 you
@@ -86,7 +86,11 @@ ship with ALSA kernels.
 
 To install, execute the following:  ---   ::
 
-   $ pip install .
+   $ python setup.py build
+
+And then as root:  ---   ::
+
+   # python setup.py install
 
 
 *******