Changes between Initial Version and Version 1 of TracDev/PluginDevelopment/ExtensionPoints/trac.env.ISystemInfoProvider

Timestamp:

Jan 22, 2012, 5:02:26 PM (12 years ago)

Author:

Peter Suter

Comment:

—

TracDev/PluginDevelopment/ExtensionPoints/trac.env.ISystemInfoProvider

@@ +1 @@
+== Extension Point : ''ISystemInfoProvider'' ==
+
+||'''Interface'''||''ISystemInfoProvider''||'''Since'''||[wiki:TracDev/ApiChanges/0.12#ISystemInfoProvider 0.12]||
+||'''Module'''||''trac''||'''Source'''||[source:trunk/trac/env.py env.py]||
+
+The ''ISystemInfoProvider'' allows reporting system and version information displayed on the [http://trac.edgewall.org/about About Trac] page and in internal error reports. 
+
+== Purpose ==
+
+Trac requires some [TracInstall#MandatoryDependencies mandatory dependencies] and can leverage various [TracInstall#OptionalDependencies optional dependencies]. Further, plugins can add their own dependencies. For administration and debugging purposes these dependencies and the respective version information is gathered and shown in the appropriate places.
+
+Plugins can add additional such information by implementing ISystemInfoProvider. Note that the plugins themselves and their respective versions are already listed automatically, so plugins should only implement this interface to report additional version information of external dependencies.
+
+== Usage ==
+
+Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
+
+A class implementing ISystemInfoProvider simply implements the `get_system_info()` method to yield name and version tuples of any used external packages.
+
+== Examples ==
+
+The following example reports platform information (i.e. the operating system and its version):
+{{{#!python
+import platform
+
+from trac.core import *
+from trac.env import ISystemInfoProvider
+
+class PlatformInfoProvider(Component):
+    """Provides platform (Operating System) information."""
+
+    implements(ISystemInfoProvider)
+
+    def get_system_info(self):
+        yield platform.system(), platform.version()
+}}}
+
+To automatically extract the version of a Python library package, use the `trac.util.get_pkginfo` utility method. For example an imaginary `pony` library could be reported as follows:
+{{{#!python
+from trac.core import *
+from trac.env import ISystemInfoProvider
+from trac.util import get_pkginfo
+
+class PonyFarm(Component):
+    """Provides ponies."""
+
+    implements(ISystemInfoProvider)
+
+    def get_system_info(self):
+        import pony
+        yield 'Pony', get_pkginfo(pony).get('version')
+        
+     # ...
+}}}
+
+== Available Implementations ==
+
+In Trac:
+ * [browser:trunk/trac/env.py trac.env.Environment]: ''Trac'', ''Python'', SetupTools and PyTz versions
+ * [browser:trunk/trac/web/chrome.py trac.web.chrome.Chrome]: [http://genshi.edgewall.org/ Genshi] and [http://babel.edgewall.org/ Babel] versions
+ * [browser:trunk/trac/versioncontrol/svn_fs.py trac.versioncontrol.svn_fs.SubversionConnector]: [TracSubversion Subversion] version
+ * [browser:trunk/trac/mimeview/rst.py trac.mimeview.rst.ReStructuredTextRenderer]: [WikiRestructuredText Docutils] version
+ * [browser:trunk/trac/mimeview/pygments.py trac.mimeview.pygments.PygmentsRenderer]: [TracSyntaxColoring#AboutPygments Pygments] version
+ * [browser:trunk/tracopt/mimeview/silvercity.py tracopt.mimeview.silvercity.SilverCityRenderer]: SilverCity version
+ 
+In plugins:
+ * [browser:plugins/0.13/mercurial-plugin/tracext/hg/backend.py tracext.hg.backend.MercurialConnector]: [TracMercurial Mercurial] version
+
+== Additional Information and References ==
+
+ * [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.env.ISystemInfoProvider-class.html epydoc]
+ * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_env.html#trac.env.ISystemInfoProvider API Reference]
+ * Related tickets:
+  * #8908 Initial implementation
+ 
+=== Other approaches: 
+Before 0.12 introduced the ISystemInfoProvider interface, it was customary to add version information by calling `self.env.systeminfo.append((name, version))`.
+
+(While this is still possible, it is usually preferrable to implement the interface to ensure that the version is shown even if the respective component has not otherwise been used yet.)
+
+This approach is still used by:
+* The database backends (so that only the database backend actually used is shown):
+ * [browser:trunk/trac/db/sqlite_backend.py trac.db.sqlite_backend.SQLiteConnector]: SQLite and pysqlite versions
+ * [browser:trunk/trac/db/postgres_backend.py trac.db.postgres_backlend.PostgreSQLConnector]: psycopg2 version
+ * [browser:trunk/trac/db/mysql_backend.py trac.db.mysql_backend.MySQLConnector]: MySQL and MySQLdb versions
+* [browser:trunk/trac/web/main.py trac.web.main.dispatch_request] for the Web front-end type and version
+
+The jQuery version is added client-side by the jQuery Javascript library itself in:
+ * the [browser:trunk/trac/templates/about.html about.html] template, or
+ * a combination of the [browser:trunk/trac/web/main.py trac.web.main.send_internal_error()] method (adds a `#JQUERY#` marker) and the [browser:trunk/trac/templates/error.html error.html] template. (See #9341)
+
+The ''User Agent'' string is also added to internal error reports client-side by Javascript.