=====
Usage
=====

This chapter describes how to use `c`.

Importing C Extension Modules
=============================

After `c` is installed, C-API extension modules can be directly imported::

	import package.my_c_mod

Where the file :file:`package/my_c_mod.py.c` exists in the Python `sys.path`.

.. note::   It is necessary for the user to have write privileges to the __pycache__ directory
            associated with the module's location.

If compilation of `my_c_mod` fails, an `ImportError` subclass will be raised with
the output of the compiler or linker.

Reading the Compilation Transcript
==================================

Compilation is often associated with a lot of information about the process.
Notably, warnings are often present in compiler output. However, the C loader
does not allow this detail to be printed to the terminal. This is desirable as
it is inappropriate for the import machinery to emit such noise. To compensate,
relevant information about the compilation process is recorded to a log file
alongside the compiled output. This output can be viewed using the
:py:mod:`c.bin.log` executable module::

	python3 -m c.bin.log package.my_c_mod