Python code coverage for Lib/packaging/database.py

#	count	content
1	n/a	"""PEP 376 implementation."""
2	n/a
3	n/a	import os
4	n/a	import re
5	n/a	import csv
6	n/a	import sys
7	n/a	import zipimport
8	n/a	from io import StringIO
9	n/a	from hashlib import md5
10	n/a
11	n/a	from packaging import logger
12	n/a	from packaging.errors import PackagingError
13	n/a	from packaging.version import suggest_normalized_version, VersionPredicate
14	n/a	from packaging.metadata import Metadata
15	n/a
16	n/a
17	n/a	__all__ = [
18	n/a	'Distribution', 'EggInfoDistribution', 'distinfo_dirname',
19	n/a	'get_distributions', 'get_distribution', 'get_file_users',
20	n/a	'provides_distribution', 'obsoletes_distribution',
21	n/a	'enable_cache', 'disable_cache', 'clear_cache',
22	n/a	# XXX these functions' names look like get_file_users but are not related
23	n/a	'get_file_path', 'get_file']
24	n/a
25	n/a
26	n/a	# TODO update docs
27	n/a
28	n/a	DIST_FILES = ('INSTALLER', 'METADATA', 'RECORD', 'REQUESTED', 'RESOURCES')
29	n/a
30	n/a	# Cache
31	n/a	_cache_name = {} # maps names to Distribution instances
32	n/a	_cache_name_egg = {} # maps names to EggInfoDistribution instances
33	n/a	_cache_path = {} # maps paths to Distribution instances
34	n/a	_cache_path_egg = {} # maps paths to EggInfoDistribution instances
35	n/a	_cache_generated = False # indicates if .dist-info distributions are cached
36	n/a	_cache_generated_egg = False # indicates if .dist-info and .egg are cached
37	n/a	_cache_enabled = True
38	n/a
39	n/a
40	n/a	def enable_cache():
41	n/a	"""
42	n/a	Enables the internal cache.
43	n/a
44	n/a	Note that this function will not clear the cache in any case, for that
45	n/a	functionality see :func:`clear_cache`.
46	n/a	"""
47	n/a	global _cache_enabled
48	n/a
49	n/a	_cache_enabled = True
50	n/a
51	n/a
52	n/a	def disable_cache():
53	n/a	"""
54	n/a	Disables the internal cache.
55	n/a
56	n/a	Note that this function will not clear the cache in any case, for that
57	n/a	functionality see :func:`clear_cache`.
58	n/a	"""
59	n/a	global _cache_enabled
60	n/a
61	n/a	_cache_enabled = False
62	n/a
63	n/a
64	n/a	def clear_cache():
65	n/a	""" Clears the internal cache. """
66	n/a	global _cache_generated, _cache_generated_egg
67	n/a
68	n/a	_cache_name.clear()
69	n/a	_cache_name_egg.clear()
70	n/a	_cache_path.clear()
71	n/a	_cache_path_egg.clear()
72	n/a	_cache_generated = False
73	n/a	_cache_generated_egg = False
74	n/a
75	n/a
76	n/a	def _yield_distributions(include_dist, include_egg, paths):
77	n/a	"""
78	n/a	Yield .dist-info and .egg(-info) distributions, based on the arguments
79	n/a
80	n/a	:parameter include_dist: yield .dist-info distributions
81	n/a	:parameter include_egg: yield .egg(-info) distributions
82	n/a	"""
83	n/a	for path in paths:
84	n/a	realpath = os.path.realpath(path)
85	n/a	if not os.path.isdir(realpath):
86	n/a	continue
87	n/a	for dir in os.listdir(realpath):
88	n/a	dist_path = os.path.join(realpath, dir)
89	n/a	if include_dist and dir.endswith('.dist-info'):
90	n/a	yield Distribution(dist_path)
91	n/a	elif include_egg and (dir.endswith('.egg-info') or
92	n/a	dir.endswith('.egg')):
93	n/a	yield EggInfoDistribution(dist_path)
94	n/a
95	n/a
96	n/a	def _generate_cache(use_egg_info, paths):
97	n/a	global _cache_generated, _cache_generated_egg
98	n/a
99	n/a	if _cache_generated_egg or (_cache_generated and not use_egg_info):
100	n/a	return
101	n/a	else:
102	n/a	gen_dist = not _cache_generated
103	n/a	gen_egg = use_egg_info
104	n/a
105	n/a	for dist in _yield_distributions(gen_dist, gen_egg, paths):
106	n/a	if isinstance(dist, Distribution):
107	n/a	_cache_path[dist.path] = dist
108	n/a	if dist.name not in _cache_name:
109	n/a	_cache_name[dist.name] = []
110	n/a	_cache_name[dist.name].append(dist)
111	n/a	else:
112	n/a	_cache_path_egg[dist.path] = dist
113	n/a	if dist.name not in _cache_name_egg:
114	n/a	_cache_name_egg[dist.name] = []
115	n/a	_cache_name_egg[dist.name].append(dist)
116	n/a
117	n/a	if gen_dist:
118	n/a	_cache_generated = True
119	n/a	if gen_egg:
120	n/a	_cache_generated_egg = True
121	n/a
122	n/a
123	n/a	class Distribution:
124	n/a	"""Created with the path of the ``.dist-info`` directory provided to the
125	n/a	constructor. It reads the metadata contained in ``METADATA`` when it is
126	n/a	instantiated."""
127	n/a
128	n/a	name = ''
129	n/a	"""The name of the distribution."""
130	n/a
131	n/a	version = ''
132	n/a	"""The version of the distribution."""
133	n/a
134	n/a	metadata = None
135	n/a	"""A :class:`packaging.metadata.Metadata` instance loaded with
136	n/a	the distribution's ``METADATA`` file."""
137	n/a
138	n/a	requested = False
139	n/a	"""A boolean that indicates whether the ``REQUESTED`` metadata file is
140	n/a	present (in other words, whether the package was installed by user
141	n/a	request or it was installed as a dependency)."""
142	n/a
143	n/a	def __init__(self, path):
144	n/a	if _cache_enabled and path in _cache_path:
145	n/a	self.metadata = _cache_path[path].metadata
146	n/a	else:
147	n/a	metadata_path = os.path.join(path, 'METADATA')
148	n/a	self.metadata = Metadata(path=metadata_path)
149	n/a
150	n/a	self.name = self.metadata['Name']
151	n/a	self.version = self.metadata['Version']
152	n/a	self.path = path
153	n/a
154	n/a	if _cache_enabled and path not in _cache_path:
155	n/a	_cache_path[path] = self
156	n/a
157	n/a	def __repr__(self):
158	n/a	return '<Distribution %r %s at %r>' % (
159	n/a	self.name, self.version, self.path)
160	n/a
161	n/a	def _get_records(self, local=False):
162	n/a	results = []
163	n/a	with self.get_distinfo_file('RECORD') as record:
164	n/a	record_reader = csv.reader(record, delimiter=',',
165	n/a	lineterminator='\n')
166	n/a	for row in record_reader:
167	n/a	missing = [None for i in range(len(row), 3)]
168	n/a	path, checksum, size = row + missing
169	n/a	if local:
170	n/a	path = path.replace('/', os.sep)
171	n/a	path = os.path.join(sys.prefix, path)
172	n/a	results.append((path, checksum, size))
173	n/a	return results
174	n/a
175	n/a	def get_resource_path(self, relative_path):
176	n/a	with self.get_distinfo_file('RESOURCES') as resources_file:
177	n/a	resources_reader = csv.reader(resources_file, delimiter=',',
178	n/a	lineterminator='\n')
179	n/a	for relative, destination in resources_reader:
180	n/a	if relative == relative_path:
181	n/a	return destination
182	n/a	raise KeyError(
183	n/a	'no resource file with relative path %r is installed' %
184	n/a	relative_path)
185	n/a
186	n/a	def list_installed_files(self, local=False):
187	n/a	"""
188	n/a	Iterates over the ``RECORD`` entries and returns a tuple
189	n/a	``(path, md5, size)`` for each line. If local is ``True``,
190	n/a	the returned path is transformed into a local absolute path.
191	n/a	Otherwise the raw value from RECORD is returned.
192	n/a
193	n/a	A local absolute path is an absolute path in which occurrences of
194	n/a	``'/'`` have been replaced by the system separator given by ``os.sep``.
195	n/a
196	n/a	:parameter local: flag to say if the path should be returned as a local
197	n/a	absolute path
198	n/a
199	n/a	:type local: boolean
200	n/a	:returns: iterator of (path, md5, size)
201	n/a	"""
202	n/a	for result in self._get_records(local):
203	n/a	yield result
204	n/a
205	n/a	def uses(self, path):
206	n/a	"""
207	n/a	Returns ``True`` if path is listed in ``RECORD``. path can be a local
208	n/a	absolute path or a relative ``'/'``-separated path.
209	n/a
210	n/a	:rtype: boolean
211	n/a	"""
212	n/a	for p, checksum, size in self._get_records():
213	n/a	local_absolute = os.path.join(sys.prefix, p)
214	n/a	if path == p or path == local_absolute:
215	n/a	return True
216	n/a	return False
217	n/a
218	n/a	def get_distinfo_file(self, path, binary=False):
219	n/a	"""
220	n/a	Returns a file located under the ``.dist-info`` directory. Returns a
221	n/a	``file`` instance for the file pointed by path.
222	n/a
223	n/a	:parameter path: a ``'/'``-separated path relative to the
224	n/a	``.dist-info`` directory or an absolute path;
225	n/a	If path is an absolute path and doesn't start
226	n/a	with the ``.dist-info`` directory path,
227	n/a	a :class:`PackagingError` is raised
228	n/a	:type path: string
229	n/a	:parameter binary: If binary is ``True``, opens the file in read-only
230	n/a	binary mode (``rb``), otherwise opens it in
231	n/a	read-only mode (``r``).
232	n/a	:rtype: file object
233	n/a	"""
234	n/a	open_flags = 'r'
235	n/a	if binary:
236	n/a	open_flags += 'b'
237	n/a
238	n/a	# Check if it is an absolute path # XXX use relpath, add tests
239	n/a	if path.find(os.sep) >= 0:
240	n/a	# it's an absolute path?
241	n/a	distinfo_dirname, path = path.split(os.sep)[-2:]
242	n/a	if distinfo_dirname != self.path.split(os.sep)[-1]:
243	n/a	raise PackagingError(
244	n/a	'dist-info file %r does not belong to the %r %s '
245	n/a	'distribution' % (path, self.name, self.version))
246	n/a
247	n/a	# The file must be relative
248	n/a	if path not in DIST_FILES:
249	n/a	raise PackagingError('invalid path for a dist-info file: %r' %
250	n/a	path)
251	n/a
252	n/a	path = os.path.join(self.path, path)
253	n/a	return open(path, open_flags)
254	n/a
255	n/a	def list_distinfo_files(self, local=False):
256	n/a	"""
257	n/a	Iterates over the ``RECORD`` entries and returns paths for each line if
258	n/a	the path is pointing to a file located in the ``.dist-info`` directory
259	n/a	or one of its subdirectories.
260	n/a
261	n/a	:parameter local: If local is ``True``, each returned path is
262	n/a	transformed into a local absolute path. Otherwise the
263	n/a	raw value from ``RECORD`` is returned.
264	n/a	:type local: boolean
265	n/a	:returns: iterator of paths
266	n/a	"""
267	n/a	for path, checksum, size in self._get_records(local):
268	n/a	# XXX add separator or use real relpath algo
269	n/a	if path.startswith(self.path):
270	n/a	yield path
271	n/a
272	n/a	def __eq__(self, other):
273	n/a	return isinstance(other, Distribution) and self.path == other.path
274	n/a
275	n/a	# See http://docs.python.org/reference/datamodel#object.__hash__
276	n/a	__hash__ = object.__hash__
277	n/a
278	n/a
279	n/a	class EggInfoDistribution:
280	n/a	"""Created with the path of the ``.egg-info`` directory or file provided
281	n/a	to the constructor. It reads the metadata contained in the file itself, or
282	n/a	if the given path happens to be a directory, the metadata is read from the
283	n/a	file ``PKG-INFO`` under that directory."""
284	n/a
285	n/a	name = ''
286	n/a	"""The name of the distribution."""
287	n/a
288	n/a	version = ''
289	n/a	"""The version of the distribution."""
290	n/a
291	n/a	metadata = None
292	n/a	"""A :class:`packaging.metadata.Metadata` instance loaded with
293	n/a	the distribution's ``METADATA`` file."""
294	n/a
295	n/a	_REQUIREMENT = re.compile(
296	n/a	r'(?P<name>[-A-Za-z0-9_.]+)\s*'
297	n/a	r'(?P<first>(?:<\|<=\|!=\|==\|>=\|>)[-A-Za-z0-9_.]+)?\s*'
298	n/a	r'(?P<rest>(?:\s,\s(?:<\|<=\|!=\|==\|>=\|>)[-A-Za-z0-9_.]+))\s'
299	n/a	r'(?P<extras>\[.*\])?')
300	n/a
301	n/a	def __init__(self, path):
302	n/a	self.path = path
303	n/a	if _cache_enabled and path in _cache_path_egg:
304	n/a	self.metadata = _cache_path_egg[path].metadata
305	n/a	self.name = self.metadata['Name']
306	n/a	self.version = self.metadata['Version']
307	n/a	return
308	n/a
309	n/a	# reused from Distribute's pkg_resources
310	n/a	def yield_lines(strs):
311	n/a	"""Yield non-empty/non-comment lines of a ``basestring``
312	n/a	or sequence"""
313	n/a	if isinstance(strs, str):
314	n/a	for s in strs.splitlines():
315	n/a	s = s.strip()
316	n/a	# skip blank lines/comments
317	n/a	if s and not s.startswith('#'):
318	n/a	yield s
319	n/a	else:
320	n/a	for ss in strs:
321	n/a	for s in yield_lines(ss):
322	n/a	yield s
323	n/a
324	n/a	requires = None
325	n/a
326	n/a	if path.endswith('.egg'):
327	n/a	if os.path.isdir(path):
328	n/a	meta_path = os.path.join(path, 'EGG-INFO', 'PKG-INFO')
329	n/a	self.metadata = Metadata(path=meta_path)
330	n/a	try:
331	n/a	req_path = os.path.join(path, 'EGG-INFO', 'requires.txt')
332	n/a	with open(req_path, 'r') as fp:
333	n/a	requires = fp.read()
334	n/a	except IOError:
335	n/a	requires = None
336	n/a	else:
337	n/a	# FIXME handle the case where zipfile is not available
338	n/a	zipf = zipimport.zipimporter(path)
339	n/a	fileobj = StringIO(
340	n/a	zipf.get_data('EGG-INFO/PKG-INFO').decode('utf8'))
341	n/a	self.metadata = Metadata(fileobj=fileobj)
342	n/a	try:
343	n/a	requires = zipf.get_data('EGG-INFO/requires.txt')
344	n/a	except IOError:
345	n/a	requires = None
346	n/a	self.name = self.metadata['Name']
347	n/a	self.version = self.metadata['Version']
348	n/a
349	n/a	elif path.endswith('.egg-info'):
350	n/a	if os.path.isdir(path):
351	n/a	path = os.path.join(path, 'PKG-INFO')
352	n/a	try:
353	n/a	with open(os.path.join(path, 'requires.txt'), 'r') as fp:
354	n/a	requires = fp.read()
355	n/a	except IOError:
356	n/a	requires = None
357	n/a	self.metadata = Metadata(path=path)
358	n/a	self.name = self.metadata['Name']
359	n/a	self.version = self.metadata['Version']
360	n/a
361	n/a	else:
362	n/a	raise ValueError('path must end with .egg-info or .egg, got %r' %
363	n/a	path)
364	n/a
365	n/a	if requires is not None:
366	n/a	if self.metadata['Metadata-Version'] == '1.1':
367	n/a	# we can't have 1.1 metadata and Setuptools requires
368	n/a	for field in ('Obsoletes', 'Requires', 'Provides'):
369	n/a	del self.metadata[field]
370	n/a
371	n/a	reqs = []
372	n/a
373	n/a	if requires is not None:
374	n/a	for line in yield_lines(requires):
375	n/a	if line.startswith('['):
376	n/a	logger.warning(
377	n/a	'extensions in requires.txt are not supported '
378	n/a	'(used by %r %s)', self.name, self.version)
379	n/a	break
380	n/a	else:
381	n/a	match = self._REQUIREMENT.match(line.strip())
382	n/a	if not match:
383	n/a	# this happens when we encounter extras; since they
384	n/a	# are written at the end of the file we just exit
385	n/a	break
386	n/a	else:
387	n/a	if match.group('extras'):
388	n/a	msg = ('extra requirements are not supported '
389	n/a	'(used by %r %s)', self.name, self.version)
390	n/a	logger.warning(msg, self.name)
391	n/a	name = match.group('name')
392	n/a	version = None
393	n/a	if match.group('first'):
394	n/a	version = match.group('first')
395	n/a	if match.group('rest'):
396	n/a	version += match.group('rest')
397	n/a	version = version.replace(' ', '') # trim spaces
398	n/a	if version is None:
399	n/a	reqs.append(name)
400	n/a	else:
401	n/a	reqs.append('%s (%s)' % (name, version))
402	n/a
403	n/a	if len(reqs) > 0:
404	n/a	self.metadata['Requires-Dist'] += reqs
405	n/a
406	n/a	if _cache_enabled:
407	n/a	_cache_path_egg[self.path] = self
408	n/a
409	n/a	def __repr__(self):
410	n/a	return '<EggInfoDistribution %r %s at %r>' % (
411	n/a	self.name, self.version, self.path)
412	n/a
413	n/a	def list_installed_files(self, local=False):
414	n/a
415	n/a	def _md5(path):
416	n/a	with open(path, 'rb') as f:
417	n/a	content = f.read()
418	n/a	return md5(content).hexdigest()
419	n/a
420	n/a	def _size(path):
421	n/a	return os.stat(path).st_size
422	n/a
423	n/a	path = self.path
424	n/a	if local:
425	n/a	path = path.replace('/', os.sep)
426	n/a
427	n/a	# XXX What about scripts and data files ?
428	n/a	if os.path.isfile(path):
429	n/a	return [(path, _md5(path), _size(path))]
430	n/a	else:
431	n/a	files = []
432	n/a	for root, dir, files_ in os.walk(path):
433	n/a	for item in files_:
434	n/a	item = os.path.join(root, item)
435	n/a	files.append((item, _md5(item), _size(item)))
436	n/a	return files
437	n/a
438	n/a	return []
439	n/a
440	n/a	def uses(self, path):
441	n/a	return False
442	n/a
443	n/a	def __eq__(self, other):
444	n/a	return (isinstance(other, EggInfoDistribution) and
445	n/a	self.path == other.path)
446	n/a
447	n/a	# See http://docs.python.org/reference/datamodel#object.__hash__
448	n/a	__hash__ = object.__hash__
449	n/a
450	n/a
451	n/a	def distinfo_dirname(name, version):
452	n/a	"""
453	n/a	The name and version parameters are converted into their
454	n/a	filename-escaped form, i.e. any ``'-'`` characters are replaced
455	n/a	with ``'_'`` other than the one in ``'dist-info'`` and the one
456	n/a	separating the name from the version number.
457	n/a
458	n/a	:parameter name: is converted to a standard distribution name by replacing
459	n/a	any runs of non- alphanumeric characters with a single
460	n/a	``'-'``.
461	n/a	:type name: string
462	n/a	:parameter version: is converted to a standard version string. Spaces
463	n/a	become dots, and all other non-alphanumeric characters
464	n/a	(except dots) become dashes, with runs of multiple
465	n/a	dashes condensed to a single dash.
466	n/a	:type version: string
467	n/a	:returns: directory name
468	n/a	:rtype: string"""
469	n/a	file_extension = '.dist-info'
470	n/a	name = name.replace('-', '_')
471	n/a	normalized_version = suggest_normalized_version(version)
472	n/a	# Because this is a lookup procedure, something will be returned even if
473	n/a	# it is a version that cannot be normalized
474	n/a	if normalized_version is None:
475	n/a	# Unable to achieve normality?
476	n/a	normalized_version = version
477	n/a	return '-'.join([name, normalized_version]) + file_extension
478	n/a
479	n/a
480	n/a	def get_distributions(use_egg_info=False, paths=None):
481	n/a	"""
482	n/a	Provides an iterator that looks for ``.dist-info`` directories in
483	n/a	``sys.path`` and returns :class:`Distribution` instances for each one of
484	n/a	them. If the parameters use_egg_info is ``True``, then the ``.egg-info``
485	n/a	files and directores are iterated as well.
486	n/a
487	n/a	:rtype: iterator of :class:`Distribution` and :class:`EggInfoDistribution`
488	n/a	instances
489	n/a	"""
490	n/a	if paths is None:
491	n/a	paths = sys.path
492	n/a
493	n/a	if not _cache_enabled:
494	n/a	for dist in _yield_distributions(True, use_egg_info, paths):
495	n/a	yield dist
496	n/a	else:
497	n/a	_generate_cache(use_egg_info, paths)
498	n/a
499	n/a	for dist in _cache_path.values():
500	n/a	yield dist
501	n/a
502	n/a	if use_egg_info:
503	n/a	for dist in _cache_path_egg.values():
504	n/a	yield dist
505	n/a
506	n/a
507	n/a	def get_distribution(name, use_egg_info=False, paths=None):
508	n/a	"""
509	n/a	Scans all elements in ``sys.path`` and looks for all directories
510	n/a	ending with ``.dist-info``. Returns a :class:`Distribution`
511	n/a	corresponding to the ``.dist-info`` directory that contains the
512	n/a	``METADATA`` that matches name for the name metadata field.
513	n/a	If no distribution exists with the given name and the parameter
514	n/a	use_egg_info is set to ``True``, then all files and directories ending
515	n/a	with ``.egg-info`` are scanned. A :class:`EggInfoDistribution` instance is
516	n/a	returned if one is found that has metadata that matches name for the
517	n/a	name metadata field.
518	n/a
519	n/a	This function only returns the first result found, as no more than one
520	n/a	value is expected. If the directory is not found, ``None`` is returned.
521	n/a
522	n/a	:rtype: :class:`Distribution` or :class:`EggInfoDistribution` or None
523	n/a	"""
524	n/a	if paths is None:
525	n/a	paths = sys.path
526	n/a
527	n/a	if not _cache_enabled:
528	n/a	for dist in _yield_distributions(True, use_egg_info, paths):
529	n/a	if dist.name == name:
530	n/a	return dist
531	n/a	else:
532	n/a	_generate_cache(use_egg_info, paths)
533	n/a
534	n/a	if name in _cache_name:
535	n/a	return _cache_name[name][0]
536	n/a	elif use_egg_info and name in _cache_name_egg:
537	n/a	return _cache_name_egg[name][0]
538	n/a	else:
539	n/a	return None
540	n/a
541	n/a
542	n/a	def obsoletes_distribution(name, version=None, use_egg_info=False):
543	n/a	"""
544	n/a	Iterates over all distributions to find which distributions obsolete
545	n/a	name.
546	n/a
547	n/a	If a version is provided, it will be used to filter the results.
548	n/a	If the argument use_egg_info is set to ``True``, then ``.egg-info``
549	n/a	distributions will be considered as well.
550	n/a
551	n/a	:type name: string
552	n/a	:type version: string
553	n/a	:parameter name:
554	n/a	"""
555	n/a	for dist in get_distributions(use_egg_info):
556	n/a	obsoleted = (dist.metadata['Obsoletes-Dist'] +
557	n/a	dist.metadata['Obsoletes'])
558	n/a	for obs in obsoleted:
559	n/a	o_components = obs.split(' ', 1)
560	n/a	if len(o_components) == 1 or version is None:
561	n/a	if name == o_components[0]:
562	n/a	yield dist
563	n/a	break
564	n/a	else:
565	n/a	try:
566	n/a	predicate = VersionPredicate(obs)
567	n/a	except ValueError:
568	n/a	raise PackagingError(
569	n/a	'distribution %r has ill-formed obsoletes field: '
570	n/a	'%r' % (dist.name, obs))
571	n/a	if name == o_components[0] and predicate.match(version):
572	n/a	yield dist
573	n/a	break
574	n/a
575	n/a
576	n/a	def provides_distribution(name, version=None, use_egg_info=False):
577	n/a	"""
578	n/a	Iterates over all distributions to find which distributions provide name.
579	n/a	If a version is provided, it will be used to filter the results. Scans
580	n/a	all elements in ``sys.path`` and looks for all directories ending with
581	n/a	``.dist-info``. Returns a :class:`Distribution` corresponding to the
582	n/a	``.dist-info`` directory that contains a ``METADATA`` that matches name
583	n/a	for the name metadata. If the argument use_egg_info is set to ``True``,
584	n/a	then all files and directories ending with ``.egg-info`` are considered
585	n/a	as well and returns an :class:`EggInfoDistribution` instance.
586	n/a
587	n/a	This function only returns the first result found, since no more than
588	n/a	one values are expected. If the directory is not found, returns ``None``.
589	n/a
590	n/a	:parameter version: a version specifier that indicates the version
591	n/a	required, conforming to the format in ``PEP-345``
592	n/a
593	n/a	:type name: string
594	n/a	:type version: string
595	n/a	"""
596	n/a	predicate = None
597	n/a	if not version is None:
598	n/a	try:
599	n/a	predicate = VersionPredicate(name + ' (' + version + ')')
600	n/a	except ValueError:
601	n/a	raise PackagingError('invalid name or version: %r, %r' %
602	n/a	(name, version))
603	n/a
604	n/a	for dist in get_distributions(use_egg_info):
605	n/a	provided = dist.metadata['Provides-Dist'] + dist.metadata['Provides']
606	n/a
607	n/a	for p in provided:
608	n/a	p_components = p.rsplit(' ', 1)
609	n/a	if len(p_components) == 1 or predicate is None:
610	n/a	if name == p_components[0]:
611	n/a	yield dist
612	n/a	break
613	n/a	else:
614	n/a	p_name, p_ver = p_components
615	n/a	if len(p_ver) < 2 or p_ver[0] != '(' or p_ver[-1] != ')':
616	n/a	raise PackagingError(
617	n/a	'distribution %r has invalid Provides field: %r' %
618	n/a	(dist.name, p))
619	n/a	p_ver = p_ver[1:-1] # trim off the parenthesis
620	n/a	if p_name == name and predicate.match(p_ver):
621	n/a	yield dist
622	n/a	break
623	n/a
624	n/a
625	n/a	def get_file_users(path):
626	n/a	"""
627	n/a	Iterates over all distributions to find out which distributions use
628	n/a	path.
629	n/a
630	n/a	:parameter path: can be a local absolute path or a relative
631	n/a	``'/'``-separated path.
632	n/a	:type path: string
633	n/a	:rtype: iterator of :class:`Distribution` instances
634	n/a	"""
635	n/a	for dist in get_distributions():
636	n/a	if dist.uses(path):
637	n/a	yield dist
638	n/a
639	n/a
640	n/a	def get_file_path(distribution_name, relative_path):
641	n/a	"""Return the path to a resource file."""
642	n/a	dist = get_distribution(distribution_name)
643	n/a	if dist is not None:
644	n/a	return dist.get_resource_path(relative_path)
645	n/a	raise LookupError('no distribution named %r found' % distribution_name)
646	n/a
647	n/a
648	n/a	def get_file(distribution_name, relative_path, args, *kwargs):
649	n/a	"""Open and return a resource file."""
650	n/a	return open(get_file_path(distribution_name, relative_path),
651	n/a	args, *kwargs)