<commit_before>.. _c-api:

Smisk C library
===========================================================

This is the C API for :mod:`smisk.core`.

Types
-------------------------------------------------

.. ctype:: byte
  
  8 bits of data.


.. ctype:: probably_call_cb
  
  Callback signature for probably_call() callbacks::
  
    int probably_call_cb ( void *userdata )


Members
-------------------------------------------------

.. cvar:: PyObject* smisk_core_module
  
  The module itself.

  .. versionadded:: 1.1

.. cvar:: PyObject* Error
  
  General error

.. cvar:: PyObject* IOError
  
  Input/output error

.. cvar:: PyObject* InvalidSessionError
  
  Session-related error

.. cvar:: PyObject* kString_http
  
  The string ``"http"``

.. cvar:: PyObject* kString_https
  
  The string ``"https"``

.. cvar:: int smisk_listensock_fileno
  
  FastCGI connection *fileno*.


Functions
-------------------------------------------------

.. cfunction:: PyObject* smisk_bind(PyObject *self, PyObject *args)


.. cfunction:: PyObject* smisk_unbind(PyObject *self)

  .. versionadded:: 1.1


.. cfunction:: PyObject* smisk_listening(PyObject *self, PyObject *args)


.. cfunction:: PyObject* smisk_uid(PyObject *self, PyObject *args)

  .. versionadded:: 1.1


.. cfunction:: PyObject* smisk_pack(PyObject *self, PyObject *args)

  .. versionadded:: 1.1


.. cfunction:: PyObject* SMISK_PyObject_GET(PyObject *object, char *attrname)
  
  Macro for getting an arbitrary attribute from `object`.
  
  This is the only way to set/get Type/Class properties.
  Based on the python interal function ``PyObject **_PyObject_GetDictPtr(PyObject *)``
  
  :Returns: A `PyString` or NULL if an exception was raised.
  
  .. versionadded:: 1.1


.. cfunction:: int SMISK_PyObject_SET(PyObject *object, char *attrname, PyObject *value)
  
  Macro for setting an arbitrary attribute of `object`.
  
  This is the only way to set/get Type/Class properties.
  Based on the python interal function ``PyObject **_PyObject_GetDictPtr(PyObject *)``
  
  :Returns: -1 is an error occured or 0 on success.
  
  .. versionadded:: 1.1


.. cfunction:: void REPLACE_OBJ(destination, new_value, type)
  
  Macro for replacing a value somewhere, releasing a reference to any previous value and 
  retaining one reference to the new value.


.. cfunction:: void ENSURE_BY_GETTER(void *direct, cfunction *getter[, error_code...])

  Macro used to ensure a lazy instance variable is available.
  ``error_code`` is executed if ``getter`` returns ``NULL``.


.. cfunction:: int SMISK_PyString_Check(PyObject *object)

  Macro for testing if `object` is a kind of string (either `str` or `unicode`).
  Workaround for a nasty bug in ``PyString_Check()``.
  
  :Returns: 1 if `object` is a kind of string, otherwise 0.


Utilities
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. cfunction:: PyObject *smisk_format_exc (PyObject *type, PyObject *value, PyObject *tb)

  :Returns: PyStringObject (new reference). Does NOT clear exception.


.. cfunction:: int PyDict_assoc_val_with_key (PyObject *dict, PyObject *val, PyObject *key)
  
  Associate value with key - if the key exists, the keys value is a list of
  values.


.. cfunction:: int smisk_parse_input_data (char *s, const char *separator, int is_cookie_data, PyObject *dict)
  
  Parse input data (query string, post url-encoded, cookie, etc).
  
  :Returns: 0 on success.


.. cfunction:: size_t smisk_stream_readline (char *str, int n, FCGX_Stream *stream)

  Read a line from a FCGI stream


.. cfunction:: void smisk_frepr_bytes (FILE *f, const char *s, size_t len)
  
  Print bytes - unsafe or outside ASCII characters are printed as \xXX
  Will print something like: bytes(4) 'm\x0dos'


.. cfunction:: double smisk_microtime (void)

  :Returns: Current time in microseconds


.. cfunction:: char smisk_size_unit (double *bytes)

  KB, GB, etc


.. cfunction:: char *smisk_encode_bin (const byte *in, size_t inlen, char *out, char bits_per_byte)
  
  Encode bytes into printable ASCII characters.
  
  Returns a pointer to the byte after the last valid character in out::
  
    nbits=4: out need to fit 40+1 bytes (base 16) (0-9, a-f)
    nbits=5: out need to fit 32+1 bytes (base 32) (0-9, a-v)
    nbits=6: out need to fit 27+1 bytes (base 64) (0-9, a-z, A-Z, "-", ",")<commit_msg>documentation updated<commit_after>.. _c-api:

Smisk C library
===========================================================

This is the C API for :mod:`smisk.core`.

Types
-------------------------------------------------

.. ctype:: byte
  
  8 bits of data.


.. ctype:: probably_call_cb
  
  Callback signature for probably_call() callbacks::
  
    int probably_call_cb ( void *userdata )


Members
-------------------------------------------------

.. cvar:: PyObject* smisk_core_module
  
  The module itself.

  .. versionadded:: 1.1

.. cvar:: PyObject* Error
  
  General error

.. cvar:: PyObject* IOError
  
  Input/output error

.. cvar:: PyObject* InvalidSessionError
  
  Session-related error

.. cvar:: PyObject* kString_http
  
  The string ``"http"``

.. cvar:: PyObject* kString_https
  
  The string ``"https"``

.. cvar:: int smisk_listensock_fileno
  
  FastCGI connection *fileno*.


Functions
-------------------------------------------------

.. cfunction:: PyObject* smisk_bind(PyObject *self, PyObject *args)


.. cfunction:: PyObject* smisk_unbind(PyObject *self)

  .. versionadded:: 1.1


.. cfunction:: PyObject* smisk_listening(PyObject *self, PyObject *args)


.. cfunction:: PyObject* smisk_uid(PyObject *self, PyObject *args)

  .. versionadded:: 1.1


.. cfunction:: PyObject* smisk_pack(PyObject *self, PyObject *args)

  .. versionadded:: 1.1


.. cfunction:: PyObject* SMISK_PyObject_GET(PyObject *object, char *attrname)
  
  Macro for getting an arbitrary attribute from `object`.
  
  This is the only way to set/get Type/Class properties.
  Based on the python interal function ``PyObject **_PyObject_GetDictPtr(PyObject *)``
  
  :Returns: A `PyString` or NULL if an exception was raised.
  
  .. versionadded:: 1.1


.. cfunction:: int SMISK_PyObject_SET(PyObject *object, char *attrname, PyObject *value)
  
  Macro for setting an arbitrary attribute of `object`.
  
  This is the only way to set/get Type/Class properties.
  Based on the python interal function ``PyObject **_PyObject_GetDictPtr(PyObject *)``
  
  :Returns: -1 is an error occured or 0 on success.
  
  .. versionadded:: 1.1


.. cfunction:: void REPLACE_OBJ(destination, new_value, type)
  
  Macro for replacing a value somewhere, releasing a reference to any previous value and 
  retaining one reference to the new value.


.. cfunction:: void ENSURE_BY_GETTER(void *direct, cfunction *getter[, error_code...])

  Macro used to ensure a lazy instance variable is available.
  ``error_code`` is executed if ``getter`` returns ``NULL``.


.. cfunction:: int SMISK_PyString_Check(PyObject *object)

  Macro for testing if `object` is a kind of string (either `str` or `unicode`).
  Workaround for a nasty bug in ``PyString_Check()``.
  
  :Returns: 1 if `object` is a kind of string, otherwise 0.


Utilities
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. cfunction:: PyObject *smisk_format_exc (PyObject *type, PyObject *value, PyObject *tb)

  :Returns: PyStringObject (new reference). Does NOT clear exception.


.. cfunction:: int PyDict_assoc_val_with_key (PyObject *dict, PyObject *val, PyObject *key)
  
  Associate value with key - if the key exists, the keys value is a list of
  values.


.. cfunction:: int smisk_parse_input_data (char *s, const char *separator, int is_cookie_data, PyObject *dict)
  
  Parse input data (query string, post url-encoded, cookie, etc).
  
  :Returns: 0 on success.


.. cfunction:: size_t smisk_stream_readline (char *str, int n, FCGX_Stream *stream)

  Read a line from a FCGI stream


.. cfunction:: void smisk_frepr_bytes (FILE *f, const char *s, size_t len)
  
  Print bytes - unsafe or outside ASCII characters are printed as \\xXX
  The output looks like: :samp:`bytes(4) 'm\\x0dos'`


.. cfunction:: double smisk_microtime (void)

  :Returns: Current time in microseconds


.. cfunction:: char smisk_size_unit (double *bytes)

  KB, GB, etc


.. cfunction:: char *smisk_encode_bin (const byte *in, size_t inlen, char *out, char bits_per_byte)
  
  Encode bytes into printable ASCII characters.
  
  Returns a pointer to the byte after the last valid character in out::
  
    nbits=4: out need to fit 40+1 bytes (base 16) (0-9, a-f)
    nbits=5: out need to fit 32+1 bytes (base 32) (0-9, a-v)
    nbits=6: out need to fit 27+1 bytes (base 64) (0-9, a-z, A-Z, "-", ",")
{'fraction_non_alphanumeric': 0.1593432007400555, 'fraction_numerical': 0.010175763182238668, 'mean_word_length': 3.1823017408123793, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '786121', 'n_tokens_mistral': 2788, 'n_tokens_neox': 2731, 'n_words': 949}