diff --git a/.github/workflows/support.yml b/.github/workflows/support.yml
index b62e98e..e0e26ce 100644
--- a/.github/workflows/support.yml
+++ b/.github/workflows/support.yml
@@ -11,16 +11,16 @@ jobs:
action:
runs-on: ubuntu-latest
steps:
- - uses: dessant/support-requests@v2
+ - uses: dessant/support-requests@v4
with:
github-token: ${{ github.token }}
support-label: 'support'
issue-comment: >
π We use the issue tracker exclusively for bug reports and feature requests.
However, this issue appears to be a support request. Please use our
- [support channels](https://github.com/kivy/pyjnius/blob/master/README.md#support)
+ [support channels](https://github.com/kivy/pyjnius/blob/master/CONTACT.md)
to get help with the project.
-
+
Let us know if this comment was made in error, and we'll be happy
to reopen the issue.
close-issue: true
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..29d18fa
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,8 @@
+In the interest of fostering an open and welcoming community, we as
+contributors and maintainers need to ensure participation in our project and
+our sister projects is a harassment-free and positive experience for everyone.
+It is vital that all interaction is conducted in a manner conveying respect,
+open-mindedness and gratitude.
+
+Please consult the [latest Kivy Code of Conduct](https://github.com/kivy/kivy/blob/master/CODE_OF_CONDUCT.md).
+
diff --git a/CONTACT.md b/CONTACT.md
new file mode 100644
index 0000000..bd8f750
--- /dev/null
+++ b/CONTACT.md
@@ -0,0 +1,6 @@
+# Contacting the Kivy Team
+
+If you are looking to contact the Kivy Team (who are responsible for managing
+the PyJNIus project), including looking for support, please see our
+latest [Contact Us](https://github.com/kivy/kivy/blob/master/CONTACT.md)
+document.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..637eaef
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,10 @@
+# Contribution Guidelines
+
+PyJNIus is part of the [Kivy](https://kivy.org) ecosystem - a large group of
+products used by many thousands of developers for free, but it
+is built entirely by the contributions of volunteers. We welcome (and rely on)
+users who want to give back to the community by contributing to the project.
+
+Contributions can come in many forms. See the latest
+[Contribution Guidelines](https://github.com/kivy/kivy/blob/master/CONTRIBUTING.md)
+for how you can help us.
diff --git a/FAQ.md b/FAQ.md
new file mode 100644
index 0000000..8e84b66
--- /dev/null
+++ b/FAQ.md
@@ -0,0 +1,15 @@
+# FAQ for PyJNIus
+
+## Introduction
+
+PyJNIus is a [Python](https://www.python.org/) library for accessing
+[Java](https://www.java.com/) classes using the
+[Java Native Interface](https://docs.oracle.com/javase/8/docs/technotes/guides/jni/)
+(JNI).
+
+Warning: the [PyPI](https://pypi.org/) package name is now
+[pyjnius](https://pypi.org/project/pyjnius/) instead of `jnius`.
+
+## No questions yet
+
+No Frequently Asked Questions have been identified yet. Please contribute some.
diff --git a/LICENSE b/LICENSE
index a25f4db..4e35060 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,4 +1,6 @@
-Copyright (c) 2010-2020 Kivy Team and other contributors
+MIT License
+
+Copyright (c) 2010-2023 Kivy Team and other contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/README.md b/README.md
index 6bcf73b..f20d8bc 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,33 @@
PyJNIus
=======
-A Python module to access Java classes as Python classes using the Java Native
-Interface (JNI).
-Warning: the pypi name is now `pyjnius` instead of `jnius`.
+PyJNIus is a [Python](https://www.python.org/) library for accessing
+[Java](https://www.java.com/) classes using the
+[Java Native Interface](https://docs.oracle.com/javase/8/docs/technotes/guides/jni/)
+(JNI).
+
+PyJNIus is managed by the [Kivy Team](https://kivy.org/about.html) and can be
+used with [python-for-android](https://github.com/kivy/python-for-android).
+
+It can also be used independently of Kivy, on desktop and mobile platforms.
+
+> [!WARNING]
+> The [PyPI](https://pypi.org/) package name is now
+[pyjnius](https://pypi.org/project/pyjnius/) instead of `jnius`.
+
+
+[](#backers)
+[](#sponsors)
+[](https://github.com/kivy/pyjnius/graphs/contributors)
+[](code_of_conduct.md)
+
+
+
[](https://github.com/kivy/pyjnius/actions)
[/badge.svg)](https://github.com/kivy/pyjnius/actions)
[](https://github.com/kivy/pyjnius/actions)
-[]()
-[](#backers)
-[](#sponsors)
+
Installation
------------
@@ -23,18 +40,18 @@ Quick overview
--------------
```python
->>> from jnius import autoclass
->>> autoclass('java.lang.System').out.println('Hello world')
-Hello world
-
->>> Stack = autoclass('java.util.Stack')
->>> stack = Stack()
->>> stack.push('hello')
->>> stack.push('world')
->>> print(stack.pop())
-world
->>> print(stack.pop())
-hello
+ >>> from jnius import autoclass
+ >>> autoclass('java.lang.System').out.println('Hello world')
+ Hello world
+
+ >>> Stack = autoclass('java.util.Stack')
+ >>> stack = Stack()
+ >>> stack.push('hello')
+ >>> stack.push('world')
+ >>> print(stack.pop())
+ world
+ >>> print(stack.pop())
+ hello
```
Usage with python-for-android
@@ -43,7 +60,7 @@ Usage with python-for-android
* Get [python-for-android](http://github.com/kivy/python-for-android)
* Compile a distribution with kivy (PyJNIus will be automatically added)
-Then, you can do this kind of things:
+Then, you can do this kind of thing:
```python
from time import sleep
@@ -53,9 +70,9 @@ Hardware = autoclass('org.renpy.android.Hardware')
print('DPI is', Hardware.getDPI())
Hardware.accelerometerEnable(True)
-for x in xrange(20):
+for x in range(20):
print(Hardware.accelerometerReading())
- sleep(.1)
+ sleep(0.1)
```
It will output something like:
@@ -109,9 +126,9 @@ class Hardware(JavaClass):
print('DPI is', Hardware.getDPI())
Hardware.accelerometerEnable()
-for x in xrange(20):
+for x in range(20):
print(Hardware.accelerometerReading())
- sleep(.1)
+ sleep(0.1)
```
You can use the `signatures` method of `JavaMethod` and `JavaMultipleMethod`, to inspect the discovered signatures of a method of an object
@@ -132,61 +149,94 @@ Make sure a Java Development Kit (JDK) is installed on your operating system if
you want to use PyJNIus on desktop. OpenJDK is known to work, and the Oracle
Java JDK should work as well.
-On windows, make sure `JAVA_HOME` points to your java installation, so PyJNIus
-can locate the `jvm.dll` file allowing it to start java. This shouldn't be
-necessary on OSX and Linux, but in case PyJNIus fails to find it, setting
+On Windows, make sure `JAVA_HOME` points to your Java installation, so PyJNIus
+can locate the `jvm.dll` file allowing it to start Java. This shouldn't be
+necessary on macOS and Linux, but in case PyJNIus fails to find it, setting
`JAVA_HOME` should help.
-Support
--------
+## License
-If you need assistance, you can ask for help on our mailing list:
+PyJNIus is [MIT licensed](LICENSE), actively developed by a great
+community and is supported by many projects managed by the
+[Kivy Organization](https://www.kivy.org/about.html).
-* User Group : https://groups.google.com/group/kivy-users
-* Email : kivy-users@googlegroups.com
+## Documentation
-We also have a Discord server:
+[Documentation for this repository](https://pyjnius.readthedocs.io/).
-[https://chat.kivy.org/](https://chat.kivy.org/)
+## Support
-Contributing
-------------
+Are you having trouble using PyJNIus or any of its related projects in the Kivy
+ecosystem?
+Is there an error you donβt understand? Are you trying to figure out how to use
+it? We have volunteers who can help!
-We love pull requests and discussing novel ideas. Check out our
-[contribution guide](http://kivy.org/docs/contribute.html) and
-feel free to improve PyJNIus.
+The best channels to contact us for support are listed in the latest
+[Contact Us](https://github.com/kivy/pyjnius/blob/master/CONTACT.md) document.
-The following mailing list and IRC channel are used exclusively for
-discussions about developing the Kivy framework and its sister projects:
+## Contributing
-* Dev Group : https://groups.google.com/group/kivy-dev
-* Email : kivy-dev@googlegroups.com
+PyJNIus is part of the [Kivy](https://kivy.org) ecosystem - a large group of
+products used by many thousands of developers for free, but it
+is built entirely by the contributions of volunteers. We welcome (and rely on)
+users who want to give back to the community by contributing to the project.
-License
--------
+Contributions can come in many forms. See the latest
+[Contribution Guidelines](https://github.com/kivy/pyjnius/blob/master/CONTRIBUTING.md)
+for how you can help us.
-PyJNIus is released under the terms of the MIT License. Please refer to the
-LICENSE file for more information.
+## Code of Conduct
+In the interest of fostering an open and welcoming community, we as
+contributors and maintainers need to ensure participation in our project and
+our sister projects is a harassment-free and positive experience for everyone.
+It is vital that all interaction is conducted in a manner conveying respect,
+open-mindedness and gratitude.
+
+Please consult the [latest Code of Conduct](https://github.com/kivy/pyjnius/blob/master/CODE_OF_CONDUCT.md).
+
+## Contributors
+
+This project exists thanks to
+[all the people who contribute](https://github.com/kivy/pyjnius/graphs/contributors).
+[[Become a contributor](CONTRIBUTING.md)].
+
+
## Backers
-Thank you to all our backers! π [[Become a backer](https://opencollective.com/kivy#backer)]
-
-
+Thank you to [all of our backers](https://opencollective.com/kivy)!
+π [[Become a backer](https://opencollective.com/kivy#backer)]
+
## Sponsors
-Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/kivy#sponsor)]
+Special thanks to
+[all of our sponsors, past and present](https://opencollective.com/kivy).
+Support this project by
+[[becoming a sponsor](https://opencollective.com/kivy#sponsor)].
+Here are our top current sponsors. Please click through to see their websites,
+and support them as they support us.
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/source/android.rst b/docs/source/android.rst
index a164d3d..c569fc1 100644
--- a/docs/source/android.rst
+++ b/docs/source/android.rst
@@ -4,7 +4,7 @@ Android
=======
Android has a great and extensive API to control devices, your application
-etc. Some parts of the Android API are directly accessible with Pyjnius but
+etc. Some parts of the Android API are directly accessible with PyJNIus but
some of them require you to code in Java.
.. note::
@@ -37,7 +37,7 @@ Recording an audio file
By looking at the `Audio Capture
`_ guide
for Android, you can see the simple steps for recording an audio file.
-Let's do it with Pyjnius::
+Let's do it with PyJNIus::
from jnius import autoclass
from time import sleep
@@ -97,7 +97,7 @@ Accessing the Activity
This example will show how to start a new Intent. Be careful: some Intents
require you to setup parts in the `AndroidManifest.xml` and have some
-actions performed within your Activity. This is out of the scope of Pyjnius but
+actions performed within your Activity. This is out of the scope of PyJNIus but
we'll show you what the best approach is for playing with it.
Using the Python-for-android project, you can access the default
@@ -131,7 +131,7 @@ Accelerometer access
--------------------
The accelerometer is a good example that shows how to write a little
-Java code that you can access later with Pyjnius.
+Java code that you can access later with PyJNIus.
The `SensorManager
`_
@@ -188,7 +188,7 @@ everything needed for accessing the accelerometer::
So we created one method named `accelerometerEnable` to activate/deactivate the
listener. And we saved the last event received in `Hardware.lastEvent`.
-Now you can use it in Pyjnius::
+Now you can use it in PyJNIus::
from time import sleep
from jnius import autoclass
@@ -226,7 +226,8 @@ Using TextToSpeech
------------------
Same as the audio capture, by looking at the `An introduction to Text-To-Speech in Android
-`_ blog post, it's easy to do it with Pyjnius::
+`_ blog post, it's easy to do it
+with PyJNIus::
from jnius import autoclass
Locale = autoclass('java.util.Locale')
diff --git a/docs/source/api.rst b/docs/source/api.rst
index 1e70852..10800a7 100644
--- a/docs/source/api.rst
+++ b/docs/source/api.rst
@@ -6,7 +6,7 @@ API
.. module:: jnius
-This part of the documentation covers all the interfaces of Pyjnius.
+This part of the documentation covers all the interfaces of PyJNIus.
Reflection classes
------------------
@@ -407,13 +407,13 @@ called from another Java method, the other Java method would see the value chang
parameters are passed by reference. The two methods share the same memory space. Only one copy of
the array data exists.
-In Pyjnius, Python calls to Java methods simulate pass by reference by copying the variable values
+In PyJNIus, Python calls to Java methods simulate pass by reference by copying the variable values
from the JVM back to Python. This extra copying will have a performance impact for large data
structures. To skip the extra copy and pass by value, use the named parameter `pass_by_reference`.
obj.method(param1, param2, param3, pass_by_reference=False)
-Since Java does not have function named parameters like Python does, they are interpreted by Pyjnius
+Since Java does not have function named parameters like Python does, they are interpreted by PyJNIus
and are not passed to the Java method.
In the above example, the `pass_by_reference` parameter will apply to all the parameters. For more
@@ -442,17 +442,17 @@ If no classpath is provided and CLASSPATH is not set, the path defaults to `'.'`
This functionality is not available on Android.
-Pyjnius and threads
+PyJNIus and threads
-------------------
.. function:: detach()
- Each time you create a native thread in Python and use Pyjnius, any call to
- Pyjnius methods will force attachment of the native thread to the current JVM.
- But you must detach it before leaving the thread, and Pyjnius cannot do it for
+ Each time you create a native thread in Python and use PyJNIus, any call to
+ PyJNIus methods will force attachment of the native thread to the current JVM.
+ But you must detach it before leaving the thread, and PyJNIus cannot do it for
you.
-Pyjnius automatically calls this `detach()` function for you when a python thread exits. This is done by
+PyJNIus automatically calls this `detach()` function for you when a python thread exits. This is done by
monkey-patching the default `run()` method of `threading.Thread` class.
So if you entirely override `run()` from your own subclass of Thread, you must call `detach()` yourself
diff --git a/docs/source/building.rst b/docs/source/building.rst
index d7416e8..3aedf64 100644
--- a/docs/source/building.rst
+++ b/docs/source/building.rst
@@ -27,7 +27,7 @@ In all cases, after checking out PyJNIus from GitHub, it can be *built* and inst
This installs `Cython `_ (as specified in the
`pyproject.toml `_)
in a Python build environment. On all platforms, if PyJNIus cannot find your JDK, you can set
-the `JAVA_HOME` shell environment variable (this is often needed on Windows).
+the `JAVA_HOME` environment variable (this is often needed on Windows).
If you want to compile the PyJNIus extension within the directory for any development,
just type::
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 6444e99..adf96d7 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -232,7 +232,7 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- ('index', 'pyjnius', u'Pyjnius Documentation',
+ ('index', 'pyjnius', u'PyJNIus Documentation',
[u'Kivy Team and other contributors'], 1)
]
@@ -246,8 +246,8 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
- ('index', 'Pyjnius', u'Pyjnius Documentation',
- u'Kivy Team and other contributors', 'Pyjnius', 'Dynamic access to Java classes from Python',
+ ('index', 'PyJNIus', u'PyJNIus Documentation',
+ u'Kivy Team and other contributors', 'PyJNIus', 'Dynamic access to Java classes from Python',
'Miscellaneous'),
]
diff --git a/docs/source/contact.rst b/docs/source/contact.rst
new file mode 100644
index 0000000..3634356
--- /dev/null
+++ b/docs/source/contact.rst
@@ -0,0 +1,8 @@
+.. _contact:
+
+Contact Us
+==========
+
+If you are looking to contact the Kivy Team (who are responsible for managing the
+PyJNIus project), including looking for support, please see our
+`latest contact details `_.
\ No newline at end of file
diff --git a/docs/source/contribute.rst b/docs/source/contribute.rst
new file mode 100644
index 0000000..ddf1e07
--- /dev/null
+++ b/docs/source/contribute.rst
@@ -0,0 +1,11 @@
+.. _contribute:
+
+Contribution Guidelines
+=======================
+
+Kivy is a large product used by many thousands of developers for free, but it
+is built entirely by the contributions of volunteers. We welcome (and rely on)
+users who want to give back to the community by contributing to the project.
+
+Contributions can come in many forms. To learn more, see our
+`latest Contribution Guidelines `_.
\ No newline at end of file
diff --git a/docs/source/faq.rst b/docs/source/faq.rst
new file mode 100644
index 0000000..e117794
--- /dev/null
+++ b/docs/source/faq.rst
@@ -0,0 +1,7 @@
+.. _faq:
+
+FAQ
+===
+
+PyJNIus has an `online FAQ `_. It contains the answers to
+questions that repeatedly come up.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 20b2dc8..e4f9792 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,14 +1,27 @@
-Welcome to Pyjnius
+Welcome to PyJNIus
==================
-Pyjnius is a Python library for accessing Java classes.
+PyJNIus is a `Python `_ library for accessing
+`Java `_ classes using the
+`Java Native Interface `
+(JNI).
+
+It either starts a new `Java Virtual machine `_
+(JVM) inside the process, or retrieves the already surrounding JVM (for example on Android).
+
+PyJNIus is managed by the `Kivy Team `_ and can be
+used with `python-for-android `_.
+
+PyJNIus is released and distributed under the terms of the MIT license. You should have received a
+copy of the MIT license alongside your Kivy distribution. Our
+`latest license `_
+is also available.
-It either starts a new JVM inside the process, or retrieves the already surrounding JVM (for example on Android).
This documentation is divided into differents parts. We recommend you to start
with :ref:`installation`, and then head over to the :ref:`quickstart`. You can
also check :ref:`android` for specific example for the Android platform. If
-you'd rather dive into the internals of Pyjnius, check out the :ref:`api`
+you'd rather dive into the internals of PyJNIus, check out the :ref:`api`
documentation.
.. toctree::
@@ -18,8 +31,10 @@ documentation.
quickstart
android
api
- building
packaging
+ contact
+ contribute
+ faq
Indices and tables
==================
diff --git a/jnius/__init__.py b/jnius/__init__.py
index c1300ef..5314269 100644
--- a/jnius/__init__.py
+++ b/jnius/__init__.py
@@ -1,5 +1,5 @@
'''
-Pyjnius
+PyJNIus
=======
Accessing Java classes from Python.
diff --git a/setup.py b/setup.py
index 3cca8c1..2f85746 100644
--- a/setup.py
+++ b/setup.py
@@ -2,18 +2,15 @@
Setup.py for creating a binary distribution.
'''
-from __future__ import print_function
-from setuptools import setup, Extension
-from setuptools.command.build_ext import build_ext
-try:
- import subprocess32 as subprocess
-except ImportError:
- import subprocess
-
from os import environ
from os.path import dirname, join
+import subprocess
import sys
+
from setup_sdist import SETUP_KWARGS
+from setuptools import setup, Extension
+from setuptools.command.build_ext import build_ext
+
# XXX hack to be able to import jnius.env withough having build
# jnius.jnius yet, better solution welcome
@@ -67,6 +64,7 @@ JAVA=get_java_setup(PLATFORM)
assert JAVA.is_jdk(), "You need a JDK, we only found a JRE. Try setting JAVA_HOME"
+
def compile_native_invocation_handler(java):
'''Find javac and compile NativeInvocationHandler.java.'''
javac = java.get_javac()
@@ -82,6 +80,7 @@ def compile_native_invocation_handler(java):
join('jnius', 'src', 'org', 'jnius', 'NativeInvocationHandler.java')
])
+
compile_native_invocation_handler(JAVA)
diff --git a/setup_sdist.py b/setup_sdist.py
index 18571a3..ab3d992 100644
--- a/setup_sdist.py
+++ b/setup_sdist.py
@@ -27,17 +27,25 @@ SETUP_KWARGS = {
'name': 'pyjnius',
'version': VERSION,
'url': "https://github.com/kivy/pyjnius",
+ 'project_urls': {
+ 'Website': "https://kivy.org",
+ 'Documentation': "https://pyjnius.readthedocs.io",
+ 'Source': "https://github.com/kivy/pyjnius",
+ 'Bug Reports': "https://github.com/kivy/pyjnius/issues",
+ },
'packages': ['jnius'],
'py_modules': ['jnius_config', 'setup', 'setup_sdist', 'jnius.env'],
'ext_package': 'jnius',
'package_data': {
'jnius': ['src/org/jnius/*'],
- },
+ },
'long_description_content_type': 'text/markdown',
'long_description': README,
'author': 'Kivy Team and other contributors',
'author_email': 'kivy-dev@googlegroups.com',
- 'description': "A Python module to access Java classes as Python classes using JNI.",
+ 'description':
+ "A Python library for accessing access Java classes as using the "
+ "Java Native Interface (JNI).",
'keywords': 'Java JNI Android',
'classifiers': [
'Development Status :: 5 - Production/Stable',