numcodecs_python/
codec.rs

1use pyo3::{
2    PyTypeInfo,
3    ffi::PyTypeObject,
4    intern,
5    prelude::*,
6    sync::GILOnceCell,
7    types::{DerefToPyAny, IntoPyDict, PyDict, PyType},
8};
9
10#[expect(unused_imports)] // FIXME: use expect, only used in docs
11use crate::PyCodecClassMethods;
12use crate::{PyCodecClass, sealed::Sealed};
13
14/// Represents a [`numcodecs.abc.Codec`] *instance* object.
15///
16/// The [`Bound<Codec>`] type implements the [`PyCodecMethods`] API.
17///
18/// [`numcodecs.abc.Codec`]: https://numcodecs.readthedocs.io/en/stable/abc.html#module-numcodecs.abc
19#[repr(transparent)]
20pub struct PyCodec {
21    _codec: PyAny,
22}
23
24/// Methods implemented for [`PyCodec`]s.
25pub trait PyCodecMethods<'py>: Sealed {
26    /// Encodes the data in the buffer `buf` and returns the result.
27    ///
28    /// The input and output buffers be any objects supporting the
29    /// [new-style buffer protocol].
30    ///
31    /// # Errors
32    ///
33    /// Errors if encoding the buffer fails.
34    ///
35    /// [new-style buffer protocol]: https://docs.python.org/3/c-api/buffer.html
36    fn encode(&self, buf: Borrowed<'_, 'py, PyAny>) -> Result<Bound<'py, PyAny>, PyErr>;
37
38    /// Decodes the data in the buffer `buf` and returns the result.
39    ///
40    /// The input and output buffers be any objects supporting the
41    /// [new-style buffer protocol].
42    ///
43    /// If the optional output buffer `out` is provided, the decoded data is
44    /// written into `out` and the `out` buffer is returned. Note that this
45    /// buffer must be exactly the right size to store the decoded data.
46    ///
47    /// If the optional output buffer `out` is *not* provided, a new output
48    /// buffer is allocated.
49    ///
50    /// # Errors
51    ///
52    /// Errors if decoding the buffer fails.
53    ///
54    /// [new-style buffer protocol]: https://docs.python.org/3/c-api/buffer.html
55    fn decode(
56        &self,
57        buf: Borrowed<'_, 'py, PyAny>,
58        out: Option<Borrowed<'_, 'py, PyAny>>,
59    ) -> Result<Bound<'py, PyAny>, PyErr>;
60
61    /// Returns a dictionary holding configuration parameters for this codec.
62    ///
63    /// The dict *must* include an `id` field with the
64    /// [`PyCodecClassMethods::codec_id`].
65    ///
66    /// The dict *must* be compatible with JSON encoding.
67    ///
68    /// # Errors
69    ///
70    /// Errors if getting the codec configuration fails.
71    fn get_config(&self) -> Result<Bound<'py, PyDict>, PyErr>;
72
73    /// Returns the [`PyCodecClass`] of this codec.
74    fn class(&self) -> Bound<'py, PyCodecClass>;
75}
76
77impl<'py> PyCodecMethods<'py> for Bound<'py, PyCodec> {
78    fn encode(&self, buf: Borrowed<'_, 'py, PyAny>) -> Result<Bound<'py, PyAny>, PyErr> {
79        let py = self.py();
80
81        self.as_any().call_method1(intern!(py, "encode"), (buf,))
82    }
83
84    fn decode(
85        &self,
86        buf: Borrowed<'_, 'py, PyAny>,
87        out: Option<Borrowed<'_, 'py, PyAny>>,
88    ) -> Result<Bound<'py, PyAny>, PyErr> {
89        let py = self.as_any().py();
90
91        self.as_any().call_method(
92            intern!(py, "decode"),
93            (buf,),
94            Some(&[(intern!(py, "out"), out)].into_py_dict(py)?),
95        )
96    }
97
98    fn get_config(&self) -> Result<Bound<'py, PyDict>, PyErr> {
99        let py = self.as_any().py();
100
101        self.as_any()
102            .call_method0(intern!(py, "get_config"))?
103            .extract()
104    }
105
106    #[expect(clippy::expect_used)]
107    fn class(&self) -> Bound<'py, PyCodecClass> {
108        // extracting a codec guarantees that its class is a codec class
109        self.as_any()
110            .get_type()
111            .extract()
112            .expect("Codec's class must be a CodecClass")
113    }
114}
115
116impl Sealed for Bound<'_, PyCodec> {}
117
118#[doc(hidden)]
119impl DerefToPyAny for PyCodec {}
120
121#[doc(hidden)]
122#[expect(unsafe_code)]
123unsafe impl PyTypeInfo for PyCodec {
124    const MODULE: Option<&'static str> = Some("numcodecs.abc");
125    const NAME: &'static str = "Codec";
126
127    #[inline]
128    fn type_object_raw(py: Python) -> *mut PyTypeObject {
129        static CODEC_TYPE: GILOnceCell<Py<PyType>> = GILOnceCell::new();
130
131        let ty = CODEC_TYPE.import(py, "numcodecs.abc", "Codec");
132
133        #[expect(clippy::expect_used)]
134        let ty = ty.expect("failed to access the `numpy.abc.Codec` type object");
135
136        ty.as_type_ptr()
137    }
138}
numcodecs_python/codec.rs

numcodecs_python/
codec.rs
