From 028c56b003c22150f674001982efaadac1ea2106 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Sat, 13 Apr 2013 13:25:50 +0200 Subject: [PATCH 01/10] docs: Add links to blog posts on commit messages --- docs/contributing.rst | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 215aea65..b8d2a6f3 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -27,8 +27,8 @@ Making changes 2. Install dependencies as described in the :ref:`installation` section. -3. Checkout a new branch (usually based on develop) and name it accordingly to - what you intend to do. +3. Checkout a new branch (usually based on ``develop``) and name it accordingly + to what you intend to do. - Features get the prefix ``feature/`` @@ -95,10 +95,22 @@ Submitting changes - One branch per feature or fix. Keep branches small and on topic. -- Follow the :ref:`style guide `_, especially make sure ``flake8`` +- Follow the :ref:`code style `, especially make sure ``flake8`` does not complain about anything. -- Send a pull request to the ``develop`` branch. +- Write good commit messages. Here's three blog posts on how to do it right: + + - `Writing Git commit messages + `_ + + - `A Note About Git Commit Messages + `_ + + - `On commit messages + `_ + +- Send a pull request to the ``develop`` branch. See the `GitHub pull request + docs `_ for help. Additional resources @@ -110,7 +122,4 @@ Additional resources - `Mailing List `_ -- `General GitHub documentation `_ - -- `GitHub pull request documentation - `_ +- `GitHub documentation `_ From e1cf8fbd2c848713c6141f2ccca3a1126901a8c1 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Sat, 13 Apr 2013 13:40:14 +0200 Subject: [PATCH 02/10] docs: Remove extensiondev draft warning --- docs/extensiondev.rst | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/extensiondev.rst b/docs/extensiondev.rst index b64ac3b6..8d0ace16 100644 --- a/docs/extensiondev.rst +++ b/docs/extensiondev.rst @@ -4,13 +4,6 @@ Extension development ********************* -.. warning:: Draft - - This document is a draft open for discussion. It shows how we imagine that - development of Mopidy extensions should become in the future, not how to - currently develop an extension for Mopidy. - - Mopidy started as simply an MPD server that could play music from Spotify. Early on Mopidy got multiple "frontends" to expose Mopidy to more than just MPD clients: for example the Last.fm frontend what scrobbles what you've listened From dbbe0fd16e73a429fecaf974ba8233b5f1e60923 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Sat, 13 Apr 2013 13:49:01 +0200 Subject: [PATCH 03/10] docs: Remove link to removed document --- docs/changelog.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index ab97bf08..8e7fbdd1 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -1493,8 +1493,7 @@ In the last two months, Mopidy's MPD frontend has gotten lots of stability fixes and error handling improvements, proper support for having the same track multiple times in a playlist, and support for IPv6. We have also fixed the choppy playback on the libspotify backend. For the road ahead of us, we got an -updated :doc:`release roadmap ` with our goals for the 0.1 to 0.3 -releases. +updated release roadmap with our goals for the 0.1 to 0.3 releases. Enjoy the best alpha relase of Mopidy ever :-) From 00075979616de803bf2e7e7e355a236ac2dd3e8e Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Sat, 13 Apr 2013 13:51:02 +0200 Subject: [PATCH 04/10] docs: Add mopidy.ext to API docs --- docs/api/ext.rst | 9 +++++++++ docs/api/index.rst | 1 + mopidy/ext.py | 7 +++++++ 3 files changed, 17 insertions(+) create mode 100644 docs/api/ext.rst diff --git a/docs/api/ext.rst b/docs/api/ext.rst new file mode 100644 index 00000000..594f5200 --- /dev/null +++ b/docs/api/ext.rst @@ -0,0 +1,9 @@ +.. _ext-api: + +************* +Extension API +************* + +.. automodule:: mopidy.ext + :synopsis: Extension API for extending Mopidy + :members: diff --git a/docs/api/index.rst b/docs/api/index.rst index 6ba44999..6313b7a5 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -11,4 +11,5 @@ API reference core audio frontends + ext http diff --git a/mopidy/ext.py b/mopidy/ext.py index 7fee6014..6e97844e 100644 --- a/mopidy/ext.py +++ b/mopidy/ext.py @@ -11,28 +11,35 @@ logger = logging.getLogger('mopidy.ext') class Extension(object): + """Base class for Mopidy extensions""" dist_name = None ext_name = None version = None def get_default_config(self): + """TODO""" raise NotImplementedError( 'Add at least a config section with "enabled = true"') def get_config_schema(self): + """TODO""" return config_utils.ExtensionConfigSchema() def validate_environment(self): + """TODO""" pass def get_frontend_classes(self): + """TODO""" return [] def get_backend_classes(self): + """TODO""" return [] def register_gstreamer_elements(self): + """TODO""" pass From a543a0167583eb508e67201fe597bad1c41ba594 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Sat, 13 Apr 2013 13:55:56 +0200 Subject: [PATCH 05/10] docs: Minor updates to extensiondev docs --- docs/extensiondev.rst | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/docs/extensiondev.rst b/docs/extensiondev.rst index 8d0ace16..d78c8c4d 100644 --- a/docs/extensiondev.rst +++ b/docs/extensiondev.rst @@ -6,7 +6,7 @@ Extension development Mopidy started as simply an MPD server that could play music from Spotify. Early on Mopidy got multiple "frontends" to expose Mopidy to more than just MPD -clients: for example the Last.fm frontend what scrobbles what you've listened +clients: for example the scrobbler frontend what scrobbles what you've listened to to your Last.fm account, the MPRIS frontend that integrates Mopidy into the Ubuntu Sound Menu, and the HTTP server and JavaScript player API making web based Mopidy clients possible. In Mopidy 0.9 we added support for multiple @@ -113,9 +113,9 @@ register themselves as available Mopidy extensions when they are installed on your system. The example below also includes a couple of convenient tricks for reading the -package version from the source code so that it it's just defined in a single -place, and to reuse the README file as the long description of the package for -the PyPI registration. +package version from the source code so that it is defined in a single place, +and to reuse the README file as the long description of the package for the +PyPI registration. The package must have ``install_requires`` on ``setuptools`` and ``Mopidy``, in addition to any other dependencies required by your extension. The @@ -182,17 +182,18 @@ Python package. The root of your Python package should have an ``__version__`` attribute with a :pep:`386` compliant version number, for example "0.1". Next, it should have a -class named ``Extension`` which inherits from Mopidy's extension base class. -This is the class referred to in the ``entry_points`` part of ``setup.py``. Any -imports of other files in your extension should be kept inside methods. This -ensures that this file can be imported without raising :exc:`ImportError` -exceptions for missing dependencies, etc. +class named ``Extension`` which inherits from Mopidy's extension base class, +:class:`mopidy.ext.Extension`. This is the class referred to in the +``entry_points`` part of ``setup.py``. Any imports of other files in your +extension should be kept inside methods. This ensures that this file can be +imported without raising :exc:`ImportError` exceptions for missing +dependencies, etc. The default configuration for the extension is defined by the ``get_default_config()`` method in the ``Extension`` class which returns a -:mod:`ConfigParser` compatible config section. The config section's name should +:mod:`ConfigParser` compatible config section. The config section's name must be the same as the extension's short name, as defined in the ``entry_points`` -part of ``setup.py``, for example ``soundspot``. All extensions should include +part of ``setup.py``, for example ``soundspot``. All extensions must include an ``enabled`` config which should default to ``true``. Provide good defaults for all config values so that as few users as possible will need to change them. The exception is if the config value has security implications; in that @@ -204,8 +205,6 @@ and ``password``. from __future__ import unicode_literals - import os - import pygst pygst.require('0.10') import gst @@ -325,8 +324,8 @@ If you want to extend Mopidy's GStreamer pipeline with new custom GStreamer elements, you'll need to register them in GStreamer before they can be used. Basically, you just implement your GStreamer element in Python and then make -your :meth:`Extension.register_gstreamer_elements` method register all your -custom GStreamer elements. +your :meth:`~mopidy.ext.Extension.register_gstreamer_elements` method register +all your custom GStreamer elements. For examples of custom GStreamer elements implemented in Python, see :mod:`mopidy.audio.mixers`. From 0052dbeb0d041da29f0ea60e100355cf20ff2234 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Sat, 13 Apr 2013 14:01:07 +0200 Subject: [PATCH 06/10] docs: Remove extension support implementation plan --- docs/extensiondev.rst | 59 ------------------------------------------- 1 file changed, 59 deletions(-) diff --git a/docs/extensiondev.rst b/docs/extensiondev.rst index d78c8c4d..5530d2f2 100644 --- a/docs/extensiondev.rst +++ b/docs/extensiondev.rst @@ -329,62 +329,3 @@ all your custom GStreamer elements. For examples of custom GStreamer elements implemented in Python, see :mod:`mopidy.audio.mixers`. - - -Implementation steps -==================== - -A rough plan of how to make the above document the reality of how Mopidy -extensions work. - -1. Implement :class:`mopidy.utils.ext.Extension` base class and the - :exc:`mopidy.exceptions.ExtensionError` exception class. - -2. Switch from using distutils to setuptools to package and install Mopidy so - that we can register entry points for the bundled extensions and get - information about all extensions available on the system from - :mod:`pkg_resources`. - -3. Add :class:`Extension` classes for all existing frontends and backends. Skip - any default config and config validation for now. - -4. Add entry points for the existing extensions in the ``setup.py`` file. - -5. Rewrite the startup procedure to find extensions and thus frontends and - backends via :mod:`pkg_resouces` instead of the ``FRONTENDS`` and - ``BACKENDS`` settings. - -6. Remove the ``FRONTENDS`` and ``BACKENDS`` settings. - -7. Add default config files and config validation to all existing extensions. - -8. Switch to ini file based configuration, using :mod:`ConfigParser`. The - default config is the combination of a core config file plus the config from - each installed extension. To find the effective config for the system, the - following config sources are added together, with the later ones overriding - the earlier ones: - - - the default config built from Mopidy core and all installed extensions, - - - ``/etc/mopidy/mopidy.conf``, - - - ``~/.config/mopidy/mopidy.conf``, - - - any config file provided via command line arguments, and - - - any config values provided via command line arguments. - -9. Replace all use of ``mopidy.settings`` with the new config object. - -10. Add command line options for: - - - loading an additional config file for this execution of Mopidy, - - - setting a config value for this execution of Mopidy, - - - printing the effective config and exit, and - - - write a config value permanently to ``~/.config/mopidy/mopidy.conf``, or - ``/etc/mopidy/mopidy.conf`` if root, and exit. - -11. Reimplement ``--list-deps`` based upon information provided by extensions. From a2e08c6d4e4a638aea2d4be2e9c039558bbae76c Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Sat, 13 Apr 2013 14:04:54 +0200 Subject: [PATCH 07/10] docs: Add note about extension's API usage --- docs/api/index.rst | 2 ++ docs/extensiondev.rst | 8 ++++++++ 2 files changed, 10 insertions(+) diff --git a/docs/api/index.rst b/docs/api/index.rst index 6313b7a5..cb7014f1 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -1,3 +1,5 @@ +.. _api-ref: + ************* API reference ************* diff --git a/docs/extensiondev.rst b/docs/extensiondev.rst index 5530d2f2..34b26e57 100644 --- a/docs/extensiondev.rst +++ b/docs/extensiondev.rst @@ -329,3 +329,11 @@ all your custom GStreamer elements. For examples of custom GStreamer elements implemented in Python, see :mod:`mopidy.audio.mixers`. + + +Use of Mopidy APIs +================== + +When writing an extension, you should only use APIs documented at +:ref:`api-ref`. Other parts of Mopidy, like :mod:`mopidy.utils` may change at +any time, and is not something extensions should rely on being stable. From 73e3a774844960e79d06f01f9e435103880b8d7c Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Sat, 13 Apr 2013 14:06:20 +0200 Subject: [PATCH 08/10] docs: Link from ext API to extensiondev --- docs/api/ext.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/api/ext.rst b/docs/api/ext.rst index 594f5200..11908920 100644 --- a/docs/api/ext.rst +++ b/docs/api/ext.rst @@ -4,6 +4,8 @@ Extension API ************* +If you want to learn how to make Mopidy extensions, read :ref:`extensiondev`. + .. automodule:: mopidy.ext :synopsis: Extension API for extending Mopidy :members: From 9d94e815ce2aab3f989e3c33d6ad6ce78324ac67 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Sat, 13 Apr 2013 14:22:37 +0200 Subject: [PATCH 09/10] docs: Note about logging in extensions --- docs/extensiondev.rst | 34 +++++++++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/docs/extensiondev.rst b/docs/extensiondev.rst index 34b26e57..446e950b 100644 --- a/docs/extensiondev.rst +++ b/docs/extensiondev.rst @@ -335,5 +335,37 @@ Use of Mopidy APIs ================== When writing an extension, you should only use APIs documented at -:ref:`api-ref`. Other parts of Mopidy, like :mod:`mopidy.utils` may change at +:ref:`api-ref`. Other parts of Mopidy, like :mod:`mopidy.utils`, may change at any time, and is not something extensions should rely on being stable. + + +Logging in extensions +===================== + +When making servers like Mopidy, logging is essential for understanding what's +going on. We use the :mod:`logging` module from Python's standard library. When +creating a logger, always namespace the logger using your Python package name +as this will be visible in Mopidy's debug log:: + + import logging + + logger = logging.getLogger('mopidy_soundspot') + +When logging at logging level ``info`` or higher (i.e. ``warning``, ``error``, +and ``critical``, but not ``debug``) the log message will be displayed to all +Mopidy users. Thus, the log messages at those levels should be well written and +easy to understand. + +As the logger name is not included in Mopidy's default logging format, you +should make it obvious from the log message who is the source of the log +message. For example:: + + Loaded 17 Soundspot playlists + +Is much better than:: + + Loaded 17 playlists + +If you want to turn on debug logging for your own extension, but not for +everything else due to the amount of noise, see the docs for the +:confval:`logging.levels/*` config section. From d232b729c9d673bbb2f6d38452d6f50d277987c0 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Sat, 13 Apr 2013 14:24:20 +0200 Subject: [PATCH 10/10] docs: Add TODOs for documenting command line options --- docs/running.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/running.rst b/docs/running.rst index 6c8d0ede..b81dbef7 100644 --- a/docs/running.rst +++ b/docs/running.rst @@ -18,3 +18,19 @@ using ``kill``:: kill `ps ax | grep mopidy | grep -v grep | cut -d' ' -f1` This can be useful e.g. if you create init script for managing Mopidy. + + +mopidy command +============== + +.. program:: mopidy + +TODO: Document all command line options + + +mopidy-scan command +=================== + +.. program:: mopidy-scan + +TODO: Document all command line options