McSinyx
/
palace
mirror of https://github.com/McSinyx/palace
1
1
Fork 0
Code Issues Releases Activity

PEP 257 compliance 

Rework docstrings following PEP 257
This commit is contained in:
Ngô Xuân Minh 2020-05-12 22:38:18 +07:00 committed by GitHub
parent 83315de9c8
commit 8285eb06c5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 46 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
src/alure.pxd
View File

@ -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()

69
src/palace.pyx
View File

@ -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,
this will be `(0, 0)`.
If `ALC_EXT_EFX` extension is unsupported, 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
this will be an empty list, otherwise there would be
If `AL_SOFT_source_resampler` extension is unsupported,
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
the resampler list will be empty and this will return 0.
If `AL_SOFT_source_resampler` extension is unsupported,
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
this will be the offset based on the decoder's read position.
"""Source offset in sample frames.
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,
the latency will be 0.
If `AL_SOFT_source_latency` extension is unsupported,
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,
the latency will be 0.
If `AL_SOFT_source_latency` extension is unsupported,
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:

2
tests/functional/test_examples.py
View File

@ -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()