190 lines
6.2 KiB
Python
190 lines
6.2 KiB
Python
'''
|
|
Garden
|
|
======
|
|
|
|
.. versionadded:: 1.7.0
|
|
|
|
.. versionchanged:: 1.11.1
|
|
|
|
Garden is a project to centralize addons for Kivy maintained by users. You can
|
|
find more information at `Kivy Garden <http://kivy-garden.github.io/>`_. All
|
|
the garden packages are centralized on the `kivy-garden Github
|
|
<https://github.com/kivy-garden>`_ repository.
|
|
|
|
.. warning::
|
|
|
|
The garden flower widgets are contributed by regular users such as
|
|
yourself. The kivy developers do not take any responsibility for the code
|
|
hosted in the garden organization repositories - we do not actively monitor
|
|
the flower repos. Please use at your own risk.
|
|
|
|
Update to garden structure
|
|
--------------------------
|
|
|
|
Starting with the kivy 1.11.0 release, kivy has
|
|
`shifted <https://github.com/kivy/kivy/wiki/Moving-kivy.garden.xxx-to-kivy_\
|
|
garden.xxx-and-kivy.deps.xxx-to-kivy_deps.xxx>`_ from using the garden legacy
|
|
tool that installs flowers with `garden install flower` where the flower
|
|
does not have a proper python package structure to flowers that can be
|
|
installed with pip and uploaded to pypi. Kivy supports the legacy garden
|
|
flowers side by side with the newer packages so the garden tool and legacy
|
|
flowers will be able to be used indefinitely. But we will only provide support
|
|
for the newer packages format in the future.
|
|
|
|
For garden package maintainers - for a guide how to migrate your garden package
|
|
from the legacy structure `garden.flower` to the newer `flower` structure used
|
|
with the pip, see `this guide
|
|
<https://kivy-garden.github.io/#guideformigratingflowersfromlegacystructure>`_.
|
|
|
|
We hope most garden packages will be converted to the newer format to help
|
|
with installation.
|
|
|
|
General Usage Guidelines
|
|
------------------------
|
|
|
|
To use a kivy garden flower, first check if the flower is in the legacy format.
|
|
If the flower name is in the format of `garden.flower`, such as
|
|
`garden.graph <https://github.com/kivy-garden/garden.graph>`_ it is a legacy
|
|
flower. If it is just `flower` such as
|
|
`graph <https://github.com/kivy-garden/graph>`_ it is in the present format.
|
|
If it is in the legacy format see `Legacy garden tool instructions`_ for how to
|
|
install and use it. Otherwise, continue with the guide below.
|
|
|
|
Garden flowers can now be installed with the `pip` tool like a normal python
|
|
package. Given a flower that you want to install, lets use
|
|
`graph <https://github.com/kivy-garden/graph>`_ as an example. You can install
|
|
master directly from github with::
|
|
|
|
python -m pip install \
|
|
https://github.com/kivy-garden/graph/archive/master.zip
|
|
|
|
Look under the repository's releases tab if you'd like to install a specific
|
|
release or a pre-compiled wheel, if the flower has any. Then use the url with
|
|
`pip`.
|
|
|
|
Or you can automatically install it using garden's pypi server with::
|
|
|
|
python -m pip install kivy_garden.graph \
|
|
--extra-index-url https://kivy-garden.github.io/simple/
|
|
|
|
To permanently add our garden server to your pip configuration so that you
|
|
don't have to specify it with `--extra-index-url`, add::
|
|
|
|
[global]
|
|
timeout = 60
|
|
index-url = https://kivy-garden.github.io/simple/
|
|
|
|
to your `pip.conf <https://pip.pypa.io/en/stable/user_guide/#config-file>`_.
|
|
|
|
If the flower maintainer has uploaded the flower to
|
|
`pypi <https://pypi.org/>`_, you can just install it with
|
|
`pip install kivy_garden.flower`.
|
|
|
|
|
|
Legacy garden tool instructions
|
|
-------------------------------
|
|
|
|
Garden is now distributed as a separate Python module, kivy-garden. You can
|
|
install it with pip::
|
|
|
|
pip install kivy-garden
|
|
|
|
The garden module does not initially include any packages. You can download
|
|
them with the garden tool installed by the pip package::
|
|
|
|
# Installing a garden package
|
|
garden install graph
|
|
|
|
# Upgrade a garden package
|
|
garden install --upgrade graph
|
|
|
|
# Uninstall a garden package
|
|
garden uninstall graph
|
|
|
|
# List all the garden packages installed
|
|
garden list
|
|
|
|
# Search new packages
|
|
garden search
|
|
|
|
# Search all the packages that contain "graph"
|
|
garden search graph
|
|
|
|
# Show the help
|
|
garden --help
|
|
|
|
All the garden packages are installed by default in `~/.kivy/garden`.
|
|
|
|
.. Note:: In previous versions of Kivy, garden was a tool at
|
|
kivy/tools/garden. This no longer exists, but the
|
|
kivy-garden module provides exactly the same functionality.
|
|
|
|
Packaging
|
|
~~~~~~~~~
|
|
|
|
If you want to include garden packages in your application, you can add `--app`
|
|
to the `install` command. This will create a `libs/garden` directory in your
|
|
current directory which will be used by `kivy.garden`.
|
|
|
|
For example::
|
|
|
|
cd myapp
|
|
garden install --app graph
|
|
|
|
|
|
'''
|
|
|
|
__path__ = 'kivy.garden'
|
|
|
|
import sys
|
|
import imp
|
|
from os.path import dirname, join, realpath, exists, abspath
|
|
from kivy import kivy_home_dir
|
|
from kivy.utils import platform
|
|
import kivy
|
|
|
|
#: system path where garden modules can be installed
|
|
garden_system_dir = join(kivy_home_dir, 'garden')
|
|
garden_kivy_dir = abspath(join(dirname(kivy.__file__), 'garden'))
|
|
|
|
#: application path where garden modules can be installed
|
|
if getattr(sys, 'frozen', False) and getattr(sys, '_MEIPASS', False):
|
|
garden_app_dir = join(realpath(sys._MEIPASS), 'libs', 'garden')
|
|
else:
|
|
garden_app_dir = join(realpath(dirname(sys.argv[0])), 'libs', 'garden')
|
|
#: Fixes issue #4030 in kivy where garden path is incorrect on iOS
|
|
if platform == "ios":
|
|
from os.path import join, dirname
|
|
import __main__
|
|
main_py_file = __main__.__file__
|
|
garden_app_dir = join(dirname(main_py_file), 'libs', 'garden')
|
|
|
|
|
|
class GardenImporter(object):
|
|
|
|
def find_module(self, fullname, path):
|
|
if path == 'kivy.garden':
|
|
return self
|
|
|
|
def load_module(self, fullname):
|
|
assert(fullname.startswith('kivy.garden'))
|
|
|
|
moddir = join(garden_kivy_dir, fullname.split('.', 2)[-1])
|
|
if exists(moddir):
|
|
return self._load_module(fullname, moddir)
|
|
|
|
modname = fullname.split('.', 1)[-1]
|
|
for directory in (garden_app_dir, garden_system_dir):
|
|
moddir = join(directory, modname)
|
|
if exists(moddir):
|
|
return self._load_module(fullname, moddir)
|
|
|
|
def _load_module(self, fullname, moddir):
|
|
mod = imp.load_module(fullname, None, moddir,
|
|
('', '', imp.PKG_DIRECTORY))
|
|
return mod
|
|
|
|
|
|
# insert the garden importer as ultimate importer
|
|
sys.meta_path.append(GardenImporter())
|