| 1 |
Metadata-Version: 2.1 |
| 2 |
Name: mercurial_extension_utils |
| 3 |
Version: 1.5.3 |
| 4 |
Summary: Mercurial Extension Utils |
| 5 |
Home-page: https://foss.heptapod.net/mercurial/mercurial-extension_utils |
| 6 |
Author: Marcin Kasperski |
| 7 |
Author-email: [email protected] |
| 8 |
License: BSD |
| 9 |
Keywords: mercurial hg extension |
| 10 |
Classifier: Development Status :: 4 - Beta |
| 11 |
Classifier: Environment :: Console |
| 12 |
Classifier: Intended Audience :: Developers |
| 13 |
Classifier: License :: DFSG approved |
| 14 |
Classifier: License :: OSI Approved :: BSD License |
| 15 |
Classifier: Programming Language :: Python :: 2 |
| 16 |
Classifier: Programming Language :: Python :: 3 |
| 17 |
Classifier: Operating System :: OS Independent |
| 18 |
Classifier: Topic :: Software Development :: Libraries :: Python Modules |
| 19 |
Classifier: Topic :: Software Development :: Version Control |
| 20 |
|
| 21 |
.. -*- mode: rst -*- |
| 22 |
|
| 23 |
==================================== |
| 24 |
Mercurial Extension Utils |
| 25 |
==================================== |
| 26 |
|
| 27 |
This module contains group of reusable functions, which I found useful |
| 28 |
while writing various Mercurial extensions. |
| 29 |
|
| 30 |
.. contents:: |
| 31 |
:local: |
| 32 |
:depth: 2 |
| 33 |
|
| 34 |
.. sectnum:: |
| 35 |
|
| 36 |
For Mercurial users |
| 37 |
=========================== |
| 38 |
|
| 39 |
This module is of no direct use for you. It is internally used by various |
| 40 |
Mercurial extensions (like `Keyring`_, `Dynamic Username`_ or `Path Pattern`_). |
| 41 |
|
| 42 |
In most cases it should be installed automatically while you install |
| 43 |
one of those extensions. See below for installation instructions in |
| 44 |
more tricky cases (in particular, for information about installation |
| 45 |
on Windows). |
| 46 |
|
| 47 |
.. note:: |
| 48 |
|
| 49 |
This document uses `Dynamic Username`_ in examples, but the |
| 50 |
same method should work for any other extension |
| 51 |
which requires ``mercurial_extension_utils``. |
| 52 |
|
| 53 |
Installing on Linux/Unix |
| 54 |
------------------------------------------------------- |
| 55 |
|
| 56 |
In typical case ``mercurial_extension_utils`` should be installed |
| 57 |
automatically, without requiring your attention, by commands like |
| 58 |
``pip install mercurial_dynamic_username``. |
| 59 |
|
| 60 |
If for some reason it did not work, just install from PyPi with:: |
| 61 |
|
| 62 |
pip install --user mercurial_extension_utils |
| 63 |
|
| 64 |
or system-wide with:: |
| 65 |
|
| 66 |
sudo pip install mercurial_extension_utils |
| 67 |
|
| 68 |
If you don't have ``pip``, try:: |
| 69 |
|
| 70 |
sudo easy_install mercurial_extension_utils |
| 71 |
|
| 72 |
Upgrade to newer version using the same commands with ``--upgrade`` |
| 73 |
option added, for example:: |
| 74 |
|
| 75 |
pip install --user --upgrade mercurial_extension_utils |
| 76 |
|
| 77 |
If you miss both ``pip``, and ``easy_install``, follow |
| 78 |
recipe from `Installing for development`_ section. |
| 79 |
|
| 80 |
Installing on Windows |
| 81 |
------------------------------------------------------- |
| 82 |
|
| 83 |
Windows Mercurial distributions (including most popular - and well |
| 84 |
deserving that - TortoiseHg_) are not using system Python (in fact, |
| 85 |
one may use Mercurial without installing Python at all), and |
| 86 |
installing into bundled Python path is uneasy. To remedy that, |
| 87 |
extensions utilizing this module handle additional methods of locating |
| 88 |
it. |
| 89 |
|
| 90 |
The following two methods of installation are available: |
| 91 |
|
| 92 |
1. If you have some Python installed, you may still install both this module, |
| 93 |
and extension using it, from PyPi. For example:: |
| 94 |
|
| 95 |
pip install mercurial_extension_utils |
| 96 |
pip install mercurial_dynamic_username |
| 97 |
|
| 98 |
This will not (yet) make the module visible to your Mercurial, but |
| 99 |
you will get all the necessary files installed on your computer. |
| 100 |
|
| 101 |
Then activate the actual extension in charge by specifying it's |
| 102 |
path, for example by writing in your ``Mercurial.ini``:: |
| 103 |
|
| 104 |
[extensions] |
| 105 |
mercurial_dynamic_username = C:/Python27/Lib/site-packages/mercurial_dynamic_username.py |
| 106 |
|
| 107 |
.. note:: |
| 108 |
|
| 109 |
This works because ``mercurial_dynamic_username.py`` checks for |
| 110 |
``mercurial_extension_utils.py`` saved in the same directory (and |
| 111 |
``pip`` installs both modules in the same place). You can get |
| 112 |
the same effect by manually downloading all files into the same |
| 113 |
directory (using ``pip`` is more handy as it tracks dependencies |
| 114 |
and supports upgrades). |
| 115 |
|
| 116 |
Upgrade with ``pip`` by adding ``--upgrade`` to it's options. |
| 117 |
|
| 118 |
2. If you don't have any Python, clone both the extension(s) |
| 119 |
repository and ``mercurial_extension_utils``` and put them in the same |
| 120 |
place, for example:: |
| 121 |
|
| 122 |
cd c:\MercurialPlugins |
| 123 |
hg clone https://foss.heptapod.net/mercurial/mercurial-extension_utils/ |
| 124 |
hg clone https://foss.heptapod.net/mercurial/mercurial-dynamic_username/ |
| 125 |
|
| 126 |
Update repositories to newest tagged versions (untagged versions |
| 127 |
may be unstable or not working). |
| 128 |
|
| 129 |
Activate the actual extension by specifying it's path, for example |
| 130 |
by writing in ``Mercurial.ini``:: |
| 131 |
|
| 132 |
[extensions] |
| 133 |
mercurial_dynamic_username = C:/MercurialPlugins/mercurial-dynamic_username/mercurial_dynamic_username.py |
| 134 |
|
| 135 |
.. note:: |
| 136 |
|
| 137 |
Directory names matter. This works because |
| 138 |
``mercurial_dynamic_username.py`` checks for |
| 139 |
``mercurial_extension_utils.py`` in |
| 140 |
``../mercurial_extension_utils`` and ``../extension_utils`` |
| 141 |
(relative to it's own location). |
| 142 |
|
| 143 |
To upgrade to new version, simply pull and update to newer tag. |
| 144 |
|
| 145 |
|
| 146 |
.. _Installing for development: |
| 147 |
|
| 148 |
Installing for development (or when everything else fails) |
| 149 |
----------------------------------------------------------- |
| 150 |
|
| 151 |
On Windows use second variant from the previous chapter (clone and activate |
| 152 |
by path). |
| 153 |
|
| 154 |
On Linux/Unix do the same. Clone all the necessary repositories, for example:: |
| 155 |
|
| 156 |
cd ~/sources/ |
| 157 |
hg clone https://foss.heptapod.net/mercurial/mercurial-extension_utils/ |
| 158 |
hg clone https://foss.heptapod.net/mercurial/mercurial-dynamic_username/ |
| 159 |
|
| 160 |
then either make it visible to Python by repeating in every repo:: |
| 161 |
|
| 162 |
pip install --user -e . |
| 163 |
|
| 164 |
or activate the extension(s) by full path, by writing in ``~/.hgrc`` |
| 165 |
something like:: |
| 166 |
|
| 167 |
[extensions] |
| 168 |
mercurial_dynamic_username = ~/sources/mercurial-dynamic_username/mercurial_dynamic_username.py |
| 169 |
|
| 170 |
|
| 171 |
For Mercurial extensions developers |
| 172 |
==================================== |
| 173 |
|
| 174 |
Available API |
| 175 |
------------------------ |
| 176 |
|
| 177 |
Provided functions are mostly tiny utilities related to configuration |
| 178 |
processing or location matching. They either extend Mercurial APIs a |
| 179 |
bit (like function to iterate config items which match regexp), or |
| 180 |
support tasks which aren't strictly Mercurial related, but happen |
| 181 |
repeatably during extension writing (like matching repository root |
| 182 |
against set of paths defined in the configuration). |
| 183 |
|
| 184 |
Noticeable part of the library handles various incompatibilities |
| 185 |
between Mercurial versions. |
| 186 |
|
| 187 |
See docstrings for details. |
| 188 |
|
| 189 |
Tests |
| 190 |
----------------------- |
| 191 |
|
| 192 |
Unit-tests can be run by:: |
| 193 |
|
| 194 |
python -m unittest discover tests/ |
| 195 |
|
| 196 |
(against current version) or:: |
| 197 |
|
| 198 |
nox |
| 199 |
|
| 200 |
(against various versions of mercurial and python). |
| 201 |
|
| 202 |
History |
| 203 |
================================================== |
| 204 |
|
| 205 |
See `HISTORY.rst`_ |
| 206 |
|
| 207 |
Repository, bug reports, enhancement suggestions |
| 208 |
=================================================== |
| 209 |
|
| 210 |
Development is tracked on HeptaPod, see |
| 211 |
https://foss.heptapod.net/mercurial/mercurial-extension_utils/ |
| 212 |
|
| 213 |
Use issue tracker there for bug reports and enhancement |
| 214 |
suggestions. |
| 215 |
|
| 216 |
Thanks to Octobus_ and `Clever Cloud`_ for hosting this service. |
| 217 |
|
| 218 |
Additional notes |
| 219 |
==================================================== |
| 220 |
|
| 221 |
Check also `Mercurial extensions I wrote`_. |
| 222 |
|
| 223 |
|
| 224 |
|
| 225 |
.. _Octobus: https://octobus.net/ |
| 226 |
.. _Clever Cloud: https://www.clever-cloud.com/ |
| 227 |
|
| 228 |
|
| 229 |
.. _Mercurial extensions I wrote: http://code.mekk.waw.pl/mercurial.html |
| 230 |
.. _Mercurial: http://mercurial.selenic.com |
| 231 |
.. _Dynamic Username: https://foss.heptapod.net/mercurial/mercurial-dynamic_username/ |
| 232 |
.. _Path Pattern: https://foss.heptapod.net/mercurial/mercurial-path_pattern/ |
| 233 |
.. _Keyring: https://foss.heptapod.net/mercurial/mercurial-keyring/ |
| 234 |
.. _HISTORY.rst: https://foss.heptapod.net/mercurial/mercurial-extension_utils/src/tip/HISTORY.rst |
| 235 |
|
| 236 |
.. _TortoiseHg: http://tortoisehg.bitbucket.org/ |
| 237 |
|