Install & Compatibility
Where this runs
tested against v0.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.343s · 20.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.9s · import 0.318s · 21MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CParser
✓ from pyclibrary import CParser
CLibrary
✓ from pyclibrary import CLibrary
This quickstart demonstrates how to use `pyclibrary.CParser` to parse a C header file and access its defined macros, structs, enums, and function prototypes. It creates a temporary header file, parses it, and prints the extracted information. While `pyclibrary` can also bind to dynamic libraries using `CLibrary`, that functionality is commented out in this example as it requires a pre-compiled C shared library.
import os
from pyclibrary import CParser
# Create a dummy header file for demonstration
header_content = '''
#define MY_VERSION_MAJOR 1
#define MY_VERSION_MINOR 0
typedef struct {
int width;
int height;
} Size;
enum Color {
RED = 0,
GREEN,
BLUE
};
int calculate_area(Size s);
void print_message(const char* msg);
'''
header_file_path = "temp_example_header.h"
with open(header_file_path, "w") as f:
f.write(header_content)
try:
# Initialize the CParser with the header file(s)
parser = CParser([header_file_path])
print("--- Parsed Macros ---")
print(f"MY_VERSION_MAJOR: {parser.macros['MY_VERSION_MAJOR']}")
print(f"MY_VERSION_MINOR: {parser.macros['MY_VERSION_MINOR']}")
print("\n--- Parsed Types ---")
print(f"Size struct definition: {parser.structs['Size']}")
print(f"Color enum definition: {parser.enums['Color']}")
print("\n--- Parsed Functions ---")
print(f"calculate_area signature: {parser.functions['calculate_area']}")
print(f"print_message signature: {parser.functions['print_message']}")
# To bind to a C library, you would typically do:
# from pyclibrary import CLibrary
# # Assuming a compiled shared library like 'libmyexample.so' or 'myexample.dll'
# # For this quickstart, we only demonstrate parsing, not live binding.
# try:
# lib = CLibrary(header_file_path, 'libmyexample.so') # Or 'myexample.dll' on Windows
# # Example function call (requires a real shared library):
# # area = lib.calculate_area(width=10, height=20).r # Access return value
# # lib.print_message(msg='Hello from Python')
# except OSError as e:
# print(f"\nCould not load C library for live binding: {e}")
except Exception as e:
print(f"An error occurred during parsing: {e}")
finally:
# Clean up the dummy header file
if os.path.exists(header_file_path):
os.remove(header_file_path)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pyclibrary'
The 'pyclibrary' package is not installed in your current Python environment, or the Python interpreter cannot locate it in its search path.
fixInstall the library using pip: `pip install pyclibrary`. If you are using a virtual environment, ensure it is activated before running the installation command.
Fail to parse a single enum.
The `CParser` in `pyclibrary` encountered an issue while attempting to parse an enumeration (enum) definition within your C header file. This can be caused by non-standard C syntax, missing prerequisite definitions, or complex preprocessor directives that `pyclibrary`'s parser cannot fully interpret.
fixExamine the specific enum definition in your C header file. Try simplifying complex macros, ensuring all related types and macros are defined or included in the parser's scope, or manually preprocessing parts of the header if the C syntax is particularly intricate. You might also need to provide `replacements` to the `CParser` for tricky preprocessor definitions.
Error in creating an instance of structure.
`pyclibrary` failed to automatically generate or instantiate a Python `ctypes` structure from a C `struct` definition found in your header file. This typically occurs when a type within the C structure is not resolvable, the C definition is malformed, or there are complexities in pointer handling or nested structures that `pyclibrary` cannot correctly map.
fixReview the C structure definition for any ambiguous or undefined types. Ensure all types used within the structure are also correctly defined and accessible to the `CParser`. For complex cases, consider manually defining the `ctypes` structure or simplifying the C header where possible.
AttributeError: 'Type' object has no attribute 'remove'
This error indicates an internal issue within `pyclibrary` where a `Type` object (representing a C type) is being incorrectly accessed or manipulated as if it possesses a `remove` method, which is not part of its standard interface. This was reported as a bug in early versions of the library.
fixThis is likely a bug in the specific `pyclibrary` version or interaction. Ensure you are using `pyclibrary` version 0.3.0 or newer, as updates often include bug fixes. If the problem persists, try to isolate the C declaration that triggers this error and simplify it, or consider reporting the issue to the `pyclibrary` GitHub repository with a minimal reproducible example.
Upgrade
Version history
0.3.0latest on PyPI · released Sep 3, 2025
Audit
Dependencies
No dependency data recorded yet.