<commit_before>
.. |build_master| image:: https://img.shields.io/travis/pleiszenburg/zugbruecke/master.svg?style=flat-square
	:target: https://travis-ci.org/pleiszenburg/zugbruecke
	:alt: Build Status: master / release

.. |docs_master| image:: https://readthedocs.org/projects/zugbruecke/badge/?version=latest&style=flat-square
	:target: http://zugbruecke.readthedocs.io/en/latest/?badge=latest
	:alt: Documentation Status: master / release

.. |build_develop| image:: https://img.shields.io/travis/pleiszenburg/zugbruecke/develop.svg?style=flat-square
	:target: https://travis-ci.org/pleiszenburg/zugbruecke
	:alt: Build Status: development branch

.. |docs_develop| image:: https://readthedocs.org/projects/zugbruecke/badge/?version=develop&style=flat-square
	:target: http://zugbruecke.readthedocs.io/en/develop/?badge=develop
	:alt: Documentation Status: development branch

.. |license| image:: https://img.shields.io/pypi/l/zugbruecke.svg?style=flat-square
	:target: https://github.com/pleiszenburg/zugbruecke/blob/master/LICENSE
	:alt: Project License: LGPLv2

.. |status| image:: https://img.shields.io/pypi/status/zugbruecke.svg?style=flat-square
	:target: https://github.com/pleiszenburg/zugbruecke/milestone/1
	:alt: Project Development Status

.. |pypi_version| image:: https://img.shields.io/pypi/v/zugbruecke.svg?style=flat-square
	:target: https://pypi.python.org/pypi/zugbruecke
	:alt: Available on PyPi - the Python Package Index

.. |pypi_versions| image:: https://img.shields.io/pypi/pyversions/zugbruecke.svg?style=flat-square
	:target: https://pypi.python.org/pypi/zugbruecke
	:alt: Available on PyPi - the Python Package Index

.. |zugbruecke_logo| image:: http://www.pleiszenburg.de/zugbruecke_logo.png
	:target: https://github.com/pleiszenburg/zugbruecke
	:alt: zugbruecke repository

|build_master| |docs_master| |build_develop| |docs_develop| |license| |status| |pypi_version| |pypi_versions|

|zugbruecke_logo|

Synopsis
========

**zugbruecke** is an EXPERIMENTAL **Python module** (currently in development **status 3/alpha**).
It allows to **call routines in Windows DLLs from Python code running on
Unices / Unix-like systems** such as Linux, MacOS or BSD.
zugbruecke is designed as a **drop-in replacement for Python's standard library's ctypes module**.
zugbruecke is **built on top of Wine**. A stand-alone Windows Python interpreter
launched in the background is used to execute the called DLL routines.
Communication between the Unix-side and the Windows/Wine-side is based on Python's
build-in multiprocessing connection capability.
zugbruecke has (limited) support for pointers, struct types and call-back functions.
zugbruecke comes with extensive logging features allowing to debug problems
associated with both itself and with Wine.
zugbruecke is written using **Python 3 syntax** and primarily targets the
**CPython** implementation of Python.

About Wine (from `winehq.org`_): *Wine (originally an acronym
for "Wine Is Not an Emulator") is a compatibility layer
capable of running Windows applications on several POSIX-compliant operating systems,
such as Linux, MacOS and BSD. Instead of simulating internal Windows logic like a
virtual machine or emulator, Wine translates Windows API calls into POSIX calls
on-the-fly, eliminating the performance and memory penalties of other methods and
allowing you to cleanly integrate Windows applications into your desktop.*

**This project is NEITHER associated NOR affiliated in any way or form with the Wine project.**

.. _winehq.org: https://www.winehq.org/

Prerequisites
=============

+--------------------+-------------------------------------------------------------------------------------------------------------+
| for usage          + - `CPython`_ 3.x (tested with 3.{4,5,6,7}) - no additional Python packages required                         +
|                    + - `Wine`_ 2.x/3.x/4.x (tested with regular & `staging`_) - expected to be in the user's `PATH`_             +
+--------------------+-------------------------------------------------------------------------------------------------------------+
| for tests          + - `pytest`_                                                                                                 +
|                    + - `mingw cross-compiler`_ - for building DLLs against which examples and tests can be run                   +
+--------------------+-------------------------------------------------------------------------------------------------------------+
| for documentation  + - `Sphinx`_                                                                                                 +
+--------------------+-------------------------------------------------------------------------------------------------------------+

.. _CPython: https://www.python.org/
.. _Wine: https://www.winehq.org/
.. _staging: https://wine-staging.com/
.. _PATH: https://en.wikipedia.org/wiki/PATH_(variable)
.. _pytest: https://www.pytest.org/
.. _mingw cross-compiler: http://mxe.cc
.. _Sphinx: http://www.sphinx-doc.org/

Installation
============

+--------------------+--------------------+-----------------------------------------------------------------------------+--------------------+
| *branch*           + *status*           + *installation*                                                              + *documentation*    +
+--------------------+--------------------+-----------------------------------------------------------------------------+--------------------+
| master (release)   + |build_master|     + ``pip install zugbruecke``                                                  + |docs_master|      +
+--------------------+--------------------+-----------------------------------------------------------------------------+--------------------+
| develop            + |build_develop|    + ``pip install git+https://github.com/pleiszenburg/zugbruecke.git@develop``  + |docs_develop|     +
+--------------------+--------------------+-----------------------------------------------------------------------------+--------------------+

Examples
========

Start an interactive Python session on your favorite Unix(-like) operating system and try the following:

.. code:: python

	import zugbruecke as ctypes
	dll_pow = ctypes.cdll.msvcrt.pow
	dll_pow.argtypes = (ctypes.c_double, ctypes.c_double)
	dll_pow.restype = ctypes.c_double
	print('You should expect "1024.0" to show up here: "%.1f".' % dll_pow(2.0, 10.0))

You have just witnessed ``msvcrt.dll``, Microsoft's C standard library (or Wine's implementation of it), in action on Unix.

**Interested in more?**

- Check the `examples`_ in zugbruecke's documentation,
- Read `ctypes' documentation`_,
- Beyond ctypes syntax, learn about `memory synchronization`_ with the ``memsync`` routine attribute [or]
- Have a look at zugbruecke's `test suite`_ showcasing its entire range of capabilities.

A lot of code, which was written with ``ctypes``' ``cdll``, ``windll`` or ``oledll``
in mind and which runs under Windows, should run just fine with zugbruecke
on Unix (assuming it does not use Windows features not supported by Wine).
For more complex calls, `memory synchronization`_ is potentially necessary.

.. _examples: http://zugbruecke.readthedocs.io/en/stable/examples.html
.. _ctypes' documentation: https://docs.python.org/3/library/ctypes.html
.. _test suite: https://github.com/pleiszenburg/zugbruecke/tree/master/tests
.. _memory synchronization: http://zugbruecke.readthedocs.io/en/latest/memsync.html

Speed
=====

zugbruecke performs reasonably well given its complexity with **less than 0.2 µs
overhead per call** in average on modern hardware. It is not (yet) optimized for
speed. Check the latest `benchmarks`_ for more details.
<commit_msg>readme: updated to new import pattern<commit_after>
.. |build_master| image:: https://img.shields.io/travis/pleiszenburg/zugbruecke/master.svg?style=flat-square
	:target: https://travis-ci.org/pleiszenburg/zugbruecke
	:alt: Build Status: master / release

.. |docs_master| image:: https://readthedocs.org/projects/zugbruecke/badge/?version=latest&style=flat-square
	:target: http://zugbruecke.readthedocs.io/en/latest/?badge=latest
	:alt: Documentation Status: master / release

.. |build_develop| image:: https://img.shields.io/travis/pleiszenburg/zugbruecke/develop.svg?style=flat-square
	:target: https://travis-ci.org/pleiszenburg/zugbruecke
	:alt: Build Status: development branch

.. |docs_develop| image:: https://readthedocs.org/projects/zugbruecke/badge/?version=develop&style=flat-square
	:target: http://zugbruecke.readthedocs.io/en/develop/?badge=develop
	:alt: Documentation Status: development branch

.. |license| image:: https://img.shields.io/pypi/l/zugbruecke.svg?style=flat-square
	:target: https://github.com/pleiszenburg/zugbruecke/blob/master/LICENSE
	:alt: Project License: LGPLv2

.. |status| image:: https://img.shields.io/pypi/status/zugbruecke.svg?style=flat-square
	:target: https://github.com/pleiszenburg/zugbruecke/milestone/1
	:alt: Project Development Status

.. |pypi_version| image:: https://img.shields.io/pypi/v/zugbruecke.svg?style=flat-square
	:target: https://pypi.python.org/pypi/zugbruecke
	:alt: Available on PyPi - the Python Package Index

.. |pypi_versions| image:: https://img.shields.io/pypi/pyversions/zugbruecke.svg?style=flat-square
	:target: https://pypi.python.org/pypi/zugbruecke
	:alt: Available on PyPi - the Python Package Index

.. |zugbruecke_logo| image:: http://www.pleiszenburg.de/zugbruecke_logo.png
	:target: https://github.com/pleiszenburg/zugbruecke
	:alt: zugbruecke repository

|build_master| |docs_master| |build_develop| |docs_develop| |license| |status| |pypi_version| |pypi_versions|

|zugbruecke_logo|

Synopsis
========

**zugbruecke** is an EXPERIMENTAL **Python module** (currently in development **status 3/alpha**).
It allows to **call routines in Windows DLLs from Python code running on
Unices / Unix-like systems** such as Linux, MacOS or BSD.
zugbruecke is designed as a **drop-in replacement for Python's standard library's ctypes module**.
zugbruecke is **built on top of Wine**. A stand-alone Windows Python interpreter
launched in the background is used to execute the called DLL routines.
Communication between the Unix-side and the Windows/Wine-side is based on Python's
build-in multiprocessing connection capability.
zugbruecke has (limited) support for pointers, struct types and call-back functions.
zugbruecke comes with extensive logging features allowing to debug problems
associated with both itself and with Wine.
zugbruecke is written using **Python 3 syntax** and primarily targets the
**CPython** implementation of Python.

About Wine (from `winehq.org`_): *Wine (originally an acronym
for "Wine Is Not an Emulator") is a compatibility layer
capable of running Windows applications on several POSIX-compliant operating systems,
such as Linux, MacOS and BSD. Instead of simulating internal Windows logic like a
virtual machine or emulator, Wine translates Windows API calls into POSIX calls
on-the-fly, eliminating the performance and memory penalties of other methods and
allowing you to cleanly integrate Windows applications into your desktop.*

**This project is NEITHER associated NOR affiliated in any way or form with the Wine project.**

.. _winehq.org: https://www.winehq.org/

Prerequisites
=============

+--------------------+-------------------------------------------------------------------------------------------------------------+
| for usage          + - `CPython`_ 3.x (tested with 3.{4,5,6,7}) - no additional Python packages required                         +
|                    + - `Wine`_ 2.x/3.x/4.x (tested with regular & `staging`_) - expected to be in the user's `PATH`_             +
+--------------------+-------------------------------------------------------------------------------------------------------------+
| for tests          + - `pytest`_                                                                                                 +
|                    + - `mingw cross-compiler`_ - for building DLLs against which examples and tests can be run                   +
+--------------------+-------------------------------------------------------------------------------------------------------------+
| for documentation  + - `Sphinx`_                                                                                                 +
+--------------------+-------------------------------------------------------------------------------------------------------------+

.. _CPython: https://www.python.org/
.. _Wine: https://www.winehq.org/
.. _staging: https://wine-staging.com/
.. _PATH: https://en.wikipedia.org/wiki/PATH_(variable)
.. _pytest: https://www.pytest.org/
.. _mingw cross-compiler: http://mxe.cc
.. _Sphinx: http://www.sphinx-doc.org/

Installation
============

+--------------------+--------------------+-----------------------------------------------------------------------------+--------------------+
| *branch*           + *status*           + *installation*                                                              + *documentation*    +
+--------------------+--------------------+-----------------------------------------------------------------------------+--------------------+
| master (release)   + |build_master|     + ``pip install zugbruecke``                                                  + |docs_master|      +
+--------------------+--------------------+-----------------------------------------------------------------------------+--------------------+
| develop            + |build_develop|    + ``pip install git+https://github.com/pleiszenburg/zugbruecke.git@develop``  + |docs_develop|     +
+--------------------+--------------------+-----------------------------------------------------------------------------+--------------------+

Examples
========

Start an interactive Python session on your favorite Unix(-like) operating system and try the following:

.. code:: python

	import zugbruecke.ctypes as ctypes
	dll_pow = ctypes.cdll.msvcrt.pow
	dll_pow.argtypes = (ctypes.c_double, ctypes.c_double)
	dll_pow.restype = ctypes.c_double
	print('You should expect "1024.0" to show up here: "%.1f".' % dll_pow(2.0, 10.0))

You have just witnessed ``msvcrt.dll``, Microsoft's C standard library (or Wine's implementation of it), in action on Unix.

**Interested in more?**

- Check the `examples`_ in zugbruecke's documentation,
- Read `ctypes' documentation`_,
- Beyond ctypes syntax, learn about `memory synchronization`_ with the ``memsync`` routine attribute [or]
- Have a look at zugbruecke's `test suite`_ showcasing its entire range of capabilities.

A lot of code, which was written with ``ctypes``' ``cdll``, ``windll`` or ``oledll``
in mind and which runs under Windows, should run just fine with zugbruecke
on Unix (assuming it does not use Windows features not supported by Wine).
For more complex calls, `memory synchronization`_ is potentially necessary.

.. _examples: http://zugbruecke.readthedocs.io/en/stable/examples.html
.. _ctypes' documentation: https://docs.python.org/3/library/ctypes.html
.. _test suite: https://github.com/pleiszenburg/zugbruecke/tree/master/tests
.. _memory synchronization: http://zugbruecke.readthedocs.io/en/latest/memsync.html

Speed
=====

zugbruecke performs reasonably well given its complexity with **less than 0.2 µs
overhead per call** in average on modern hardware. It is not (yet) optimized for
speed. Check the latest `benchmarks`_ for more details.

{'fraction_non_alphanumeric': 0.24169184290030213, 'fraction_numerical': 0.0034711062544192325, 'mean_word_length': 1.9924985574148875, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 48, 'lorem ipsum': 0, 'www.': 12, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 26, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '40373', 'n_tokens_mistral': 4331, 'n_tokens_neox': 4103, 'n_words': 1189}