# OpenCV Python API docs **URL:** \ **Category:** Python\ **Tags:** documentation\ **Created:** [May 3, 2024, 7:19pm UTC](https://forum.opencv.org/t/opencv-python-api-docs/17519 "2024-05-03T19:19:33Z")\ **Posts on this page:** 10\ **Page:** 1
**Author:** ![ethanc8](https://sea2.discourse-cdn.com/flex020/user_avatar/forum.opencv.org/ethanc8/32/8411_2.png) [@ethanc8](https://forum.opencv.org/u/ethanc8)\ **Post date:** [May 3, 2024, 7:19pm UTC](https://forum.opencv.org/t/opencv-python-api-docs/17519/1 "2024-05-03T19:19:33Z")
For a long time, OpenCV’s Python bindings have been solely documented through the C++ Doxygen API docs. cv2’s API is not exactly the same as the C++ API, as it’s bridged to NumPy rather than using cv::Mat and similar types. It also isn’t trivial to build documentation for cv2 using the normal Python tools, as the docstrings are written in Doxygen rather than reStructuredText. I wrote a tool to parse these docstrings and use the Python `ast` module to parse the type stubs (`*.pyi` files) which document the types of the attributes and functions. You can find that code here: [GitHub - ethanc8/opencv-doc-parser](https://github.com/ethanc8/opencv-doc-parser) Using this tool, I’ve started some work-in-progress API docs for `cv2`. So far, I have docs for `cv2.aruco` here: [cv2.aruco - OpenCV Python API 4.9.0 documentation](https://ethanc8.github.io/opencv-python-docs/aruco.html) ---
**Author:** ![ethanc8](https://sea2.discourse-cdn.com/flex020/user_avatar/forum.opencv.org/ethanc8/32/8411_2.png) [@ethanc8](https://forum.opencv.org/u/ethanc8)\ **Post date:** [May 3, 2024, 7:25pm UTC](https://forum.opencv.org/t/opencv-python-api-docs/17519/2 "2024-05-03T19:25:48Z")
Once I can parse all the docstrings into working documentation, I’ll look into trying to use parts of [pgi-docgen](https://github.com/pygobject/pgi-docgen) to make the documentation easier to browse, like [pgi-docs](https://lazka.github.io/pgi-docs/) is. ---
**Author:** ![ethanc8](https://sea2.discourse-cdn.com/flex020/user_avatar/forum.opencv.org/ethanc8/32/8411_2.png) [@ethanc8](https://forum.opencv.org/u/ethanc8)\ **Post date:** [May 3, 2024, 8:51pm UTC](https://forum.opencv.org/t/opencv-python-api-docs/17519/3 "2024-05-03T20:51:29Z")
[I also started a thread on ChiefDelphi: [https://www.chiefdelphi.com/t/opencv-python-api-docs/465238](https://www.chiefdelphi.com/t/opencv-python-api-docs/465238)] ---
**Author:** ![crackwitz](https://sea2.discourse-cdn.com/flex020/user_avatar/forum.opencv.org/crackwitz/32/14_2.png) [@crackwitz](https://forum.opencv.org/u/crackwitz)\ **Post date:** [May 4, 2024, 6:55am UTC](https://forum.opencv.org/t/opencv-python-api-docs/17519/4 "2024-05-04T06:55:45Z")
I hope you didn’t miss the Python signatures that are already _written_ in the docs. They just lack type annotations. Which isn’t much of a problem. The Python/C++ mapping is very regular. ---
**Author:** ![berak](https://avatars.discourse-cdn.com/v4/letter/b/85f322/32.png) [@berak](https://forum.opencv.org/u/berak)\ **Post date:** [May 4, 2024, 10:22am UTC](https://forum.opencv.org/t/opencv-python-api-docs/17519/5 "2024-05-04T10:22:17Z")
> [@ethanc8](#): > > So far, I have docs for `cv2.aruco` here: [cv2.aruco - OpenCV Python API 4.9.0 documentation](https://ethanc8.github.io/opencv-python-docs/aruco.html) hmm, just saying, there will be [no such module](https://docs.opencv.org/5.x/) in upcoming 5.x (keeping this up-to-date (manually !) will require super-human effort …) ---
**Author:** ![berak](https://avatars.discourse-cdn.com/v4/letter/b/85f322/32.png) [@berak](https://forum.opencv.org/u/berak)\ **Post date:** [May 4, 2024, 10:25am UTC](https://forum.opencv.org/t/opencv-python-api-docs/17519/6 "2024-05-04T10:25:45Z")
> [@ethanc8](#): > > Once I can parse all the docstrings into working documentation maybe rather [inquire, how those get there](https://github.com/opencv/opencv/tree/4.x/doc/tools) ---
**Author:** ![ethanc8](https://sea2.discourse-cdn.com/flex020/user_avatar/forum.opencv.org/ethanc8/32/8411_2.png) [@ethanc8](https://forum.opencv.org/u/ethanc8)\ **Post date:** [May 4, 2024, 2:19pm UTC](https://forum.opencv.org/t/opencv-python-api-docs/17519/7 "2024-05-04T14:19:31Z")
> (keeping this up-to-date (manually !) will require super-human effort …) Currently, the only part that needs to be done manually is listing out the names of the modules that we want to document. Even then, we can easily automate that part. ---
**Author:** ![ethanc8](https://sea2.discourse-cdn.com/flex020/user_avatar/forum.opencv.org/ethanc8/32/8411_2.png) [@ethanc8](https://forum.opencv.org/u/ethanc8)\ **Post date:** [May 4, 2024, 3:55pm UTC](https://forum.opencv.org/t/opencv-python-api-docs/17519/8 "2024-05-04T15:55:25Z")
I’m already parsing the function docstrings into mostly-working documentation. Cross-references within the briefs and descriptions are currently still using the C++ names, and are not being detected, but other than that it’s working fine. A bigger issue is the classes and constants. For some reason, the classes do not have docstrings (I don’t know how to fix that), while Python doesn’t support adding docstrings to constants. Also, the enums in OpenCV’s C++ API are imported into Python as normal constants, which means that it’s a bit annoying to document them as enums so far. ---
**Author:** ![ethanc8](https://sea2.discourse-cdn.com/flex020/user_avatar/forum.opencv.org/ethanc8/32/8411_2.png) [@ethanc8](https://forum.opencv.org/u/ethanc8)\ **Post date:** [May 4, 2024, 3:57pm UTC](https://forum.opencv.org/t/opencv-python-api-docs/17519/9 "2024-05-04T15:57:39Z")
The Python/C++ mapping is not very well documented, and there are types in OpenCV’s C++ API that I could never figure out the Python equivalent. I think I ran into this with cv::SparseMat. Also, I think that the idea of requiring users to use NumPy rather than cv::Mat and such was already a bad idea, since not only was the NumPy-to-OpenCV C++ mappings not well-documented, but cv::Mat etc had features that NumPy’s matrices didn’t. ---
**Author:** ![crackwitz](https://sea2.discourse-cdn.com/flex020/user_avatar/forum.opencv.org/crackwitz/32/14_2.png) [@crackwitz](https://forum.opencv.org/u/crackwitz)\ **Post date:** [May 4, 2024, 5:12pm UTC](https://forum.opencv.org/t/opencv-python-api-docs/17519/10 "2024-05-04T17:12:26Z")
> [@ethanc8](#): > > but cv::Mat etc had features that NumPy’s matrices didn’t. it’s the other way around. numpy arrays can represent basically everything that a cv::Mat can, but cv::Mat can’t represent some numpy arrays. that is why the OpenCV bindings have to reject some numpy inputs, or copy them to make them contiguous (one of the requirements of cv::Mat). nobody wants to use a “cv::Mat” type in Python. that thing used to exist. it was a war crime. don’t bring that back. if you try, I’ll make sure you stand trial in The Hague. Same goes for _**all (!!!)**_ the little throwaway structs and whatnot, which merely hold a small list of things. Those do _ **not** _ need to be represented in Python. structs that hold a dozen parameters may be a good idea to “be a thing”, but mostly for autocompletion. if you want to improve OpenCV, survey existing C++/Python mapping libraries and evaluate them. and you should take your enthusiasm to opencv’s github. that’s where development happens, and where issues/features are discussed. on this forum, you can get help with many things but not with architectural overhauls of OpenCV.