Skip to content

Commit 2b45feb

Browse files
filmorfilmor
committed
Current state
1 parent bd48dc1 commit 2b45feb

File tree

12 files changed

+3544
-0
lines changed

12 files changed

+3544
-0
lines changed

‎.github/workflows/docs.yml

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: Docs
2+
3+
on:
4+
#push:
5+
# branches-ignore:
6+
# - '**'
7+
push:
8+
branches: [ master, release ]
9+
pull_request:
10+
branches: [ master, release ]
11+
12+
jobs:
13+
build:
14+
15+
runs-on: ubuntu-latest
16+
17+
steps:
18+
- name: Install Doxygen
19+
run: sudo apt-get install doxygen -y
20+
shell: bash
21+
- name: Checkout repo
22+
uses: actions/checkout@1.0.0
23+
- name: Requirements
24+
run: pip install -f doc/requirements.txt
25+
- name: Build docs
26+
run: cd doc
27+
&& doxygen
28+
&& make html
29+
&& cd build/html

‎doc/.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
doxygen_xml/
2+
build/

‎doc/Doxyfile

+2,656
Large diffs are not rendered by default.

‎doc/Makefile

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎doc/make.bat

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎doc/requirements.txt

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
sphinx
2+
furo
3+
myst-parser
4+
breathe

‎doc/source/_static/.keep

Whitespace-only changes.

‎doc/source/conf.py

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file only contains a selection of the most common options. For a full
4+
# list see the documentation:
5+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
6+
7+
# -- Path setup --------------------------------------------------------------
8+
9+
# If extensions (or modules to document with autodoc) are in another directory,
10+
# add these directories to sys.path here. If the directory is relative to the
11+
# documentation root, use os.path.abspath to make it absolute, like shown here.
12+
#
13+
# import os
14+
# import sys
15+
# sys.path.insert(0, os.path.abspath('.'))
16+
17+
18+
# -- Project information -----------------------------------------------------
19+
20+
project = 'Python.NET'
21+
copyright = '2022, The Python.NET Project Contributors'
22+
author = 'The Python.NET Project Contributors'
23+
24+
25+
# -- General configuration ---------------------------------------------------
26+
27+
# Add any Sphinx extension module names here, as strings. They can be
28+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
29+
# ones.
30+
extensions = [
31+
'myst_parser',
32+
'breathe',
33+
]
34+
35+
# Add any paths that contain templates here, relative to this directory.
36+
templates_path = ['_templates']
37+
38+
# List of patterns, relative to source directory, that match files and
39+
# directories to ignore when looking for source files.
40+
# This pattern also affects html_static_path and html_extra_path.
41+
exclude_patterns = []
42+
43+
44+
# -- Options for HTML output -------------------------------------------------
45+
46+
# The theme to use for HTML and HTML Help pages. See the documentation for
47+
# a list of builtin themes.
48+
#
49+
html_theme = 'furo'
50+
51+
# Add any paths that contain custom static files (such as style sheets) here,
52+
# relative to this directory. They are copied after the builtin static files,
53+
# so a file named "default.css" will overwrite the builtin "default.css".
54+
html_static_path = ['_static']
55+
56+
breathe_projects = { "pythonnet": "../doxygen_xml" }
57+
breathe_default_project = 'pythonnet'

‎doc/source/dotnet.md

+136
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Embedding Python into .NET
2+
3+
**Note:** because Python code running under Python.NET is inherently
4+
unverifiable, it runs totally under the radar of the security infrastructure
5+
of the CLR so you should restrict use of the Python assembly to trusted code.
6+
7+
The Python runtime assembly defines a number of public classes that
8+
provide a subset of the functionality provided by the Python C-API.
9+
10+
These classes include PyObject, PyList, PyDict, PyTuple, etc.
11+
12+
At a very high level, to embed Python in your application you will need to:
13+
14+
- Reference Python.Runtime.dll in your build environment
15+
- Call PythonEngine.Initialize() to initialize Python
16+
- Call PythonEngine.ImportModule(name) to import a module
17+
18+
The module you import can either start working with your managed app
19+
environment at the time its imported, or you can explicitly lookup and
20+
call objects in a module you import.
21+
22+
For general-purpose information on embedding Python in applications,
23+
use www.python.org or Google to find (C) examples. Because
24+
Python.NET is so closely integrated with the managed environment,
25+
you will generally be better off importing a module and deferring to
26+
Python code as early as possible rather than writing a lot of managed
27+
embedding code.
28+
29+
**Important Note for embedders:** Python is not free-threaded and
30+
uses a global interpreter lock to allow multi-threaded applications
31+
to interact safely with the Python interpreter.
32+
Much more information about this is available in the Python C-API
33+
documentation on the www.python.org Website.
34+
35+
When embedding Python in a managed application, you have to manage the
36+
GIL in just the same way you would when embedding Python in
37+
a C or C++ application.
38+
39+
Before interacting with any of the objects or APIs provided by the
40+
Python.Runtime namespace, calling code must have acquired the Python
41+
global interpreter lock by calling the `PythonEngine.AcquireLock` method.
42+
The only exception to this rule is the `PythonEngine.Initialize` method,
43+
which may be called at startup without having acquired the GIL.
44+
45+
When finished using Python APIs, managed code must call a corresponding
46+
`PythonEngine.ReleaseLock` to release the GIL and allow other threads
47+
to use Python.
48+
49+
A `using` statement may be used to acquire and release the GIL:
50+
51+
```csharp
52+
using (Py.GIL())
53+
{
54+
PythonEngine.Exec("doStuff()");
55+
}
56+
```
57+
58+
The AcquireLock and ReleaseLock methods are thin wrappers over the
59+
unmanaged `PyGILState_Ensure` and `PyGILState_Release` functions from
60+
the Python API, and the documentation for those APIs applies to
61+
the managed versions.
62+
63+
## Passing C# Objects to the Python Engine
64+
65+
This section demonstrates how to pass a C# object to the Python runtime.
66+
The example uses the following `Person` class:
67+
68+
```csharp
69+
public class Person
70+
{
71+
public Person(string firstName, string lastName)
72+
{
73+
FirstName = firstName;
74+
LastName = lastName;
75+
}
76+
77+
public string FirstName { get; set; }
78+
public string LastName { get; set; }
79+
}
80+
```
81+
82+
In order to pass a C# object to the Python runtime, it must be converted to a
83+
`PyObject`. This is done using the `ToPython()` extension method. The `PyObject`
84+
may then be set as a variable in a `PyScope`. Code executed from the scope
85+
will have access to the variable:
86+
87+
```csharp
88+
// create a person object
89+
Person person = new Person("John", "Smith");
90+
91+
// acquire the GIL before using the Python interpreter
92+
using (Py.GIL())
93+
{
94+
// create a Python scope
95+
using (PyScope scope = Py.CreateScope())
96+
{
97+
// convert the Person object to a PyObject
98+
PyObject pyPerson = person.ToPython();
99+
100+
// create a Python variable "person"
101+
scope.Set("person", pyPerson);
102+
103+
// the person object may now be used in Python
104+
string code = "fullName = person.FirstName + ' ' + person.LastName";
105+
scope.Exec(code);
106+
}
107+
}
108+
```
109+
110+
[1]: http://www.ironpython.com
111+
112+
[2]: http://pythonnet.github.io/
113+
114+
[3]: https://mail.python.org/mailman3/lists/pythonnet.python.org/
115+
116+
[4]: https://mail.python.org/archives/list/pythonnet@python.org/
117+
118+
[5]: https://github.com/pythonnet/pythonnet/releases
119+
120+
[6]: https://pypi.python.org/pypi/pythonnet
121+
122+
[7]: http://www.go-mono.com
123+
124+
[8]: https://github.com/pythonnet/pythonnet/blob/master/README.rst#embedding-python-in-net
125+
126+
[9]: http://pythonnet.github.io/LICENSE
127+
128+
[10]: http://www.python.org/license.html
129+
130+
[55]: http://github.com/pythonnet/pythonnet/issues
131+
132+
[77]: http://github.com/pythonnet/pythonnet
133+
134+
[78]: https://github.com/pythonnet/pythonnet/wiki/Installation
135+
136+
[79]: https://github.com/pythonnet/pythonnet/wiki

‎doc/source/index.rst

+66
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
.. Python.NET documentation master file, created by
2+
sphinx-quickstart on Thu May 26 12:32:51 2022.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Welcome to Python.NET's documentation!
7+
======================================
8+
9+
Python.NET (`pythonnet`) is a package that gives Python programmers nearly
10+
seamless integration with the .NET 4.0+ Common Language Runtime (CLR) on Windows
11+
and Mono runtime on Linux and OSX. Python.NET provides a powerful application
12+
scripting tool for .NET developers. Using this package you can script .NET
13+
applications or build entire applications in Python, using .NET services and
14+
components written in any language that targets the CLR (C#, VB.NET, F#,
15+
C++/CLI).
16+
17+
Note that this package does _not_ implement Python as a first-class CLR
18+
language - it does not produce managed code (IL) from Python code. Rather,
19+
it is an integration of the CPython engine with the .NET or Mono runtime.
20+
This approach allows you to use CLR services and continue to use existing
21+
Python code and C-API extensions while maintaining native execution
22+
speeds for Python code. If you are interested in a pure managed-code
23+
implementation of the Python language, you should check out the
24+
`IronPython`_ project.
25+
26+
Python.NET is currently compatible and tested with Python releases from 3.7
27+
onwards.
28+
29+
Current releases are available on `PyPi <https://pypi.org/project/pythonnet/>`_
30+
and `Nuget.org <https://nuget.org/packages/pythonnet>`_.
31+
32+
To subscribe to the `Python.NET mailing list <ml_>`_ or read the
33+
`online archives`_ of the list, see the `mailing list information <ml_>`_
34+
page. Use the `Python.NET issue tracker`_ to report issues.
35+
36+
.. _IronPython: https://ironpython.net/
37+
.. _ml: https://mail.python.org/mailman3/lists/pythonnet.python.org/
38+
.. _online archives: https://mail.python.org/archives/list/pythonnet@python.org/
39+
.. _Python.NET issue tracker: https://github.com/pythonnet/pythonnet/issues
40+
41+
.. toctree::
42+
:maxdepth: 2
43+
:caption: Contents:
44+
45+
python
46+
dotnet
47+
reference
48+
49+
Indices and tables
50+
==================
51+
52+
* :ref:`genindex`
53+
* :ref:`modindex`
54+
* :ref:`search`
55+
56+
License
57+
=======
58+
59+
Python.NET is released under the open source MIT License. A copy of the license
60+
is included in the distribution, or you can find a copy of the license
61+
online.
62+
63+
.NET Foundation
64+
===============
65+
66+
This project is supported by the `.NET Foundation <https://dotnetfoundation.org>`_.

0 commit comments

Comments
 (0)