PEP 257 compliance

Rework docstrings following PEP 257

src/alure.pxd

@@ -264,11 +264,13 @@ cdef extern from 'alure2.h' namespace 'alure' nogil:
 
         @staticmethod
         void make_current 'MakeCurrent'(Context) except +
+
         @staticmethod
         Context get_current 'GetCurrent'() except +
 
         @staticmethod
         void make_thread_current 'MakeThreadCurrent'(Context) except +
+
         @staticmethod
         Context get_thread_current 'GetThreadCurrent'() except +
 
@@ -518,6 +520,7 @@ cdef extern from 'alure2.h' namespace 'alure' nogil:
     cdef cppclass FileIOFactory:
         @staticmethod
         unique_ptr[FileIOFactory] set(unique_ptr[FileIOFactory])
+
         @staticmethod
         FileIOFactory& get()
 

src/palace.pyx

@@ -235,7 +235,7 @@ def query_extension(name: str) -> bool:
 def thread_local(state: bool) -> Iterator[None]:
     """Return a context manager controlling preference of local thread.
 
-    Effectively, it sets the fallback value for the `thread` argument
+    Effectively, it sets fallback value for `thread` argument
     for `current_context` and `use_context`.
 
     Initially, globally current `Context` is preferred.
@@ -418,6 +418,7 @@ cdef class DeviceNames:
     capture : Tuple[str, ...]
         Capture device names, with the first one being the default.
     """
+
     cdef readonly tuple basic
     cdef readonly tuple full
     cdef readonly tuple capture
@@ -473,6 +474,7 @@ cdef class Device:
     --------
     device_names : Available device names
     """
+
     cdef alure.Device impl
 
     def __init__(self, name: str = '', fallback: Iterable[str] = ()) -> None:
@@ -552,8 +554,7 @@ cdef class Device:
     def efx_version(self) -> Tuple[int, int]:
         """EFX version supported by this device.
 
-        If the `ALC_EXT_EFX` extension is unsupported,
+        If `ALC_EXT_EFX` extension is unsupported, this will be (0, 0).
-        this will be `(0, 0)`.
         """
         cdef alure.Version version = self.impl.get_efx_version()
         return version.get_major(), version.get_minor()
@@ -578,7 +579,7 @@ cdef class Device:
         The order is retained from OpenAL, such that the index of
         a given name is the ID to use with `ALC_HRTF_ID_SOFT`.
 
-        If the `ALC_SOFT_HRTF` extension is unavailable,
+        If `ALC_SOFT_HRTF` extension is unavailable,
         this will be an empty list.
         """
         return self.impl.enumerate_hrtf_names()
@@ -587,7 +588,7 @@ cdef class Device:
     def hrtf_enabled(self) -> bool:
         """Whether HRTF is enabled on the device.
 
-        If the `ALC_SOFT_HRTF` extension is unavailable,
+        If `ALC_SOFT_HRTF` extension is unavailable,
         this will return False although there could still be
         HRTF applied at a lower hardware level.
         """
@@ -605,7 +606,7 @@ cdef class Device:
     def reset(self, attrs: Dict[int, int] = {}) -> None:
         """Reset the device, using the specified attributes.
 
-        If the `ALC_SOFT_HRTF` extension is unavailable,
+        If `ALC_SOFT_HRTF` extension is unavailable,
         this will be a no-op.
         """
         self.impl.reset(mkattrs(attrs.items()))
@@ -616,7 +617,7 @@ cdef class Device:
         Multiple calls are allowed but it is not reference counted,
         so the device will resume after one `resume_dsp` call.
 
-        This requires the `ALC_SOFT_pause_device` extension.
+        This requires `ALC_SOFT_pause_device` extension.
         """
         self.impl.pause_dsp()
 
@@ -689,6 +690,7 @@ cdef class Context:
     RuntimeError
         If context creation fails.
     """
+
     cdef alure.Context impl
     cdef alure.Context previous
     cdef readonly Device device
@@ -798,8 +800,8 @@ cdef class Context:
     def available_resamplers(self) -> List[str]:
         """The list of resamplers supported by the context.
 
-        If the `AL_SOFT_source_resampler` extension is unsupported
+        If `AL_SOFT_source_resampler` extension is unsupported,
-        this will be an empty list, otherwise there would be
+        this will be an empty list. Otherwise there would be
         at least one entry.
 
         This method require the context to be current.
@@ -812,8 +814,8 @@ cdef class Context:
     def default_resampler_index(self) -> int:
         """The context's default resampler index.
 
-        If the `AL_SOFT_source_resampler` extension is unsupported
+        If `AL_SOFT_source_resampler` extension is unsupported,
-        the resampler list will be empty and this will return 0.
+        this will return 0.
 
         If you try to access the resampler list with this index
         without extension, undefined behavior will occur
@@ -893,6 +895,7 @@ cdef class Listener:
     RuntimeError
         If there is neither any context specified nor current.
     """
+
     cdef alure.Listener impl
 
     def __init__(self, context: Optional[Context] = None) -> None:
@@ -976,6 +979,7 @@ cdef class Buffer:
     RuntimeError
         If there is neither any context specified nor current.
     """
+
     cdef alure.Buffer impl
     cdef Context context
     cdef readonly str name
@@ -1106,7 +1110,7 @@ cdef class Buffer:
     def loop_points(self) -> Tuple[int, int]:
         """Loop points for looping sources.
 
-        If the `AL_SOFT_loop_points` extension is not supported by the
+        If `AL_SOFT_loop_points` extension is not supported by the
         current context, `start = 0` and `end = length` respectively.
         Otherwise, `start < end <= length`.
 
@@ -1178,6 +1182,7 @@ cdef class Source:
     RuntimeError
         If there is neither any context specified nor current.
     """
+
     cdef alure.Source impl
 
     def __init__(self, context: Optional[Context] = None) -> None:
@@ -1297,8 +1302,10 @@ cdef class Source:
 
     @property
     def offset(self) -> int:
-        """Source offset in sample frames.  For streaming sources
+        """Source offset in sample frames.
-        this will be the offset based on the decoder's read position.
+
+        For streaming sources, this will be
+        based on decoder's read position.
         """
         return self.impl.get_sample_offset()
 
@@ -1310,8 +1317,8 @@ cdef class Source:
     def latency(self) -> int:
         """Source latency in nanoseconds.
 
-        If the `AL_SOFT_source_latency` extension is unsupported,
+        If `AL_SOFT_source_latency` extension is unsupported,
-        the latency will be 0.
+        this will be 0.
         """
         return self.impl.get_sample_offset_latency().second.count()
 
@@ -1319,7 +1326,7 @@ cdef class Source:
     def offset_seconds(self) -> float:
         """Source offset in seconds.
 
-        For streaming sources this will be the offset based on
+        For streaming sources, this will be based on
         the decoder's read position.
         """
         return self.impl.get_sec_offset().count()
@@ -1328,8 +1335,8 @@ cdef class Source:
     def latency_seconds(self) -> float:
         """Source latency in seconds.
 
-        If the `AL_SOFT_source_latency` extension is unsupported,
+        If `AL_SOFT_source_latency` extension is unsupported,
-        the latency will be 0.
+        this will be 0.
         """
         return self.impl.get_sec_offset_latency().second.count()
 
@@ -1470,7 +1477,7 @@ cdef class Source:
 
         Notes
         -----
-        Unlike the `AL_EXT_BFORMAT` extension this property
+        Unlike `AL_EXT_BFORMAT` extension this property
         comes from, this also affects the facing direction.
         """
         cdef pair[alure.Vector3, alure.Vector3] o = self.impl.get_orientation()
@@ -1604,7 +1611,7 @@ cdef class Source:
     def radius(self) -> float:
         """Radius of the source, as if it is a sound-emitting sphere.
 
-        This has no effect without the `AL_EXT_SOURCE_RADIUS` extension.
+        This has no effect without `AL_EXT_SOURCE_RADIUS` extension.
 
         Raises
         ------
@@ -1625,7 +1632,7 @@ cdef class Source:
         and positive values going left.
 
         This is only used for stereo playback and has no effect
-        without the `AL_EXT_STEREO_ANGLES` extension.
+        without `AL_EXT_STEREO_ANGLES` extension.
         """
         return self.impl.get_stereo_angles()
 
@@ -1644,7 +1651,7 @@ cdef class Source:
         a mono sound or not, default).
 
         This has no effect without
-        the `AL_SOFT_source_spatialize` extension.
+        `AL_SOFT_source_spatialize` extension.
         """
         cdef alure.Spatialize value = self.impl.get_3d_spatialize()
         if value == alure.Spatialize.Auto: return None
@@ -1788,6 +1795,7 @@ cdef class AuxiliarySends:
     by indexing the object with a nonnegative integer less than
     the device's `max_auxiliary_sends`.
     """
+
     cdef Source source
 
     def __init__(self, source: Source) -> None:
@@ -1862,7 +1870,7 @@ cdef class SourceGroup:
 
     @property
     def parent_group(self) -> SourceGroup:
-        """The source group this source group is a child of.
+        """The parent source group of this source group.
 
         Raises
         ------
@@ -1975,6 +1983,7 @@ cdef class BaseEffect:
     ReverbEffect : Environmental reverberation effect
     ChorusEffect : Chorus effect
     """
+
     cdef alure.AuxiliaryEffectSlot slot
     cdef alure.Effect impl
 
@@ -2073,6 +2082,7 @@ cdef class ReverbEffect(BaseEffect):
     RuntimeError
         If there is neither any context specified nor current.
     """
+
     cdef alure.EFXEAXREVERBPROPERTIES properties
 
     def __init__(self, preset: str = 'GENERIC',
@@ -2428,6 +2438,7 @@ cdef class ChorusEffect(BaseEffect):
     RuntimeError
         If there is neither any context specified nor current.
     """
+
     cdef alure.EFXCHORUSPROPERTIES properties
 
     def __init__(self, waveform: str = 'triangle',
@@ -2540,6 +2551,7 @@ cdef class Decoder:
     may only initialize an internal one.  To use registered factories,
     please call the module-level `decode` function instead.
     """
+
     cdef shared_ptr[alure.Decoder] pimpl
 
     def __init__(self, name: str, context: Optional[Context] = None) -> None:
@@ -2585,7 +2597,7 @@ cdef class Decoder:
         return self.length / self.frequency
 
     def seek(self, pos: int) -> bool:
-        """Seek to pos, specified in sample frames.
+        """Seek to `pos`, specified in sample frames.
 
         Return if the seek was successful.
         """
@@ -2664,6 +2676,7 @@ cdef class _BaseDecoder(Decoder):
 
     This class is NOT meant to be instantiated.
     """
+
     def __cinit__(self, *args, **kwargs) -> None:
         self.pimpl = shared_ptr[alure.Decoder](new CppDecoder(self))
 
@@ -2806,6 +2819,7 @@ class FileIO(Protocol):
     Since PEP 544 is only implemented in Python 3.8+, type checking
     for this on earlier Python version might not work as expected.
     """
+
     @abstractmethod
     def read(self, size: int) -> bytes:
         """Read at most size bytes, returned as bytes."""
@@ -2881,6 +2895,7 @@ cdef class MessageHandler:
 
     Exceptions raised from `MessageHandler` instances are ignored.
     """
+
     cdef list stopped_sources
 
     def __cinit__(self, *args, **kwargs) -> None:
@@ -2890,7 +2905,7 @@ cdef class MessageHandler:
         """Handle disconnected device messages.
 
         This is called when the given device has been disconnected and
-        is no longer usable for output.  As per the `ALC_EXT_disconnect`
+        is no longer usable for output.  As per `ALC_EXT_disconnect`
         specification, disconnected devices remain valid, however all
         playing sources are automatically stopped, any sources that are
         attempted to play will immediately stop, and new contexts may
@@ -2901,7 +2916,7 @@ cdef class MessageHandler:
         Connection status is checked during `Context.update` calls, so
         method must be called regularly to be notified when a device is
         disconnected.  This method may not be called if the device lacks
-        support for the `ALC_EXT_disconnect` extension.
+        support for `ALC_EXT_disconnect` extension.
         """
 
     def source_stopped(self, source: Source) -> None:

tests/functional/test_examples.py

@@ -47,7 +47,7 @@ skipif_travis_macos = mark.skipif(travis_macos, reason='Travis CI for macOS')
 
 
 def capture(*argv):
-    """Return the captured standard output of the given Python script."""
+    """Return the captured standard output of given Python script."""
     return run([executable, *argv], stdout=PIPE).stdout.decode()