main
elukjanovica
parent
8fcc0ea7d0
commit
ef4f3fa3ea
80
main.py
80
main.py
|
|
@ -1,33 +1,19 @@
|
||||||
from flask import Flask, render_template, redirect, request, session, url_for
|
from flask import Flask, render_template, redirect, request, session, url_for
|
||||||
from flask_sqlalchemy import SQLAlchemy
|
from flask_sqlalchemy import SQLAlchemy
|
||||||
from flask_admin import Admin
|
from flask_admin import Admin, AdminIndexView, expose
|
||||||
from flask_admin.contrib.sqla import ModelView
|
from flask_admin.contrib.sqla import ModelView
|
||||||
from flask_security import Security, SQLAlchemyUserDatastore, UserMixin, RoleMixin
|
|
||||||
|
|
||||||
app = Flask(__name__)
|
app = Flask(__name__)
|
||||||
app.secret_key = 'bebra'
|
app.secret_key = 'bebra'
|
||||||
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///Picture_Puzzle_web.db'
|
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///Picture_Puzzle_web.db'
|
||||||
app.config['SECURITY_PASSWORD_SALT'] = app.config['SECRET_KEY']
|
|
||||||
db = SQLAlchemy(app)
|
db = SQLAlchemy(app)
|
||||||
|
|
||||||
# Define models for Flask-Security
|
class User(db.Model):
|
||||||
roles_users = db.Table('roles_users',
|
|
||||||
db.Column('user_id', db.Integer(), db.ForeignKey('user.id')),
|
|
||||||
db.Column('role_id', db.Integer(), db.ForeignKey('role.id'))
|
|
||||||
)
|
|
||||||
|
|
||||||
class Role(db.Model, RoleMixin):
|
|
||||||
id = db.Column(db.Integer(), primary_key=True)
|
|
||||||
name = db.Column(db.String(80), unique=True)
|
|
||||||
|
|
||||||
class User(db.Model, UserMixin):
|
|
||||||
id = db.Column(db.Integer, primary_key=True)
|
id = db.Column(db.Integer, primary_key=True)
|
||||||
username = db.Column(db.String(255), unique=True)
|
username = db.Column(db.String(100), unique=True, nullable=False)
|
||||||
email = db.Column(db.String(255), unique=True)
|
password = db.Column(db.String(100), nullable=False)
|
||||||
password = db.Column(db.String(255))
|
email = db.Column(db.String(100), unique=True, nullable=False)
|
||||||
active = db.Column(db.Boolean())
|
|
||||||
roles = db.relationship('Role', secondary=roles_users,
|
|
||||||
backref=db.backref('users', lazy='dynamic'))
|
|
||||||
|
|
||||||
class Post(db.Model):
|
class Post(db.Model):
|
||||||
id = db.Column(db.Integer, primary_key=True)
|
id = db.Column(db.Integer, primary_key=True)
|
||||||
|
|
@ -36,21 +22,50 @@ class Post(db.Model):
|
||||||
title = db.Column(db.String(100), nullable=False)
|
title = db.Column(db.String(100), nullable=False)
|
||||||
image = db.Column(db.String(100), nullable=False)
|
image = db.Column(db.String(100), nullable=False)
|
||||||
|
|
||||||
user_datastore = SQLAlchemyUserDatastore(db, User, Role)
|
class MyAdminIndexView(AdminIndexView):
|
||||||
security = Security(app, user_datastore)
|
@expose('/')
|
||||||
|
def index(self):
|
||||||
|
if not session.get('admin_logged_in'):
|
||||||
|
return redirect(url_for('admin_login'))
|
||||||
|
return self.render('admin/index.html')
|
||||||
|
|
||||||
admin = Admin(app, name='Admin Panel', template_mode='bootstrap3')
|
class UserAdminView(ModelView):
|
||||||
admin.add_view(ModelView(User, db.session))
|
column_exclude_list = ['password']
|
||||||
admin.add_view(ModelView(Role, db.session))
|
form_excluded_columns = ['password']
|
||||||
|
|
||||||
def create_tables():
|
class PostAdminView(ModelView):
|
||||||
with app.app_context():
|
pass
|
||||||
db.create_all()
|
|
||||||
|
|
||||||
def register_admin_views():
|
class TableAdminView(ModelView):
|
||||||
admin = Admin(app, name='Admin Panel', template_mode='bootstrap3')
|
can_delete = True
|
||||||
admin.add_view(ModelView(User, db.session))
|
can_create = True
|
||||||
admin.add_view(ModelView(Post, db.session))
|
can_edit = True
|
||||||
|
column_display_pk = True
|
||||||
|
|
||||||
|
admin = Admin(app, name='Admin Panel', template_mode='bootstrap3', index_view=MyAdminIndexView())
|
||||||
|
|
||||||
|
admin.add_view(UserAdminView(User, db.session))
|
||||||
|
admin.add_view(PostAdminView(Post, db.session))
|
||||||
|
|
||||||
|
ADMIN_USERNAME = 'eluk'
|
||||||
|
ADMIN_PASSWORD = '1234'
|
||||||
|
|
||||||
|
@app.route("/admin/login", methods=["GET", "POST"])
|
||||||
|
def admin_login():
|
||||||
|
if request.method == "POST":
|
||||||
|
username = request.form["username"]
|
||||||
|
password = request.form["password"]
|
||||||
|
if username == ADMIN_USERNAME and password == ADMIN_PASSWORD:
|
||||||
|
session["admin_logged_in"] = True
|
||||||
|
return redirect(url_for("admin.index"))
|
||||||
|
else:
|
||||||
|
return render_template("admin/login.html", error_msg="Invalid credentials")
|
||||||
|
return render_template("admin/login.html", error_msg=None)
|
||||||
|
|
||||||
|
@app.route("/admin/logout")
|
||||||
|
def admin_logout():
|
||||||
|
session.pop("admin_logged_in", None)
|
||||||
|
return redirect(url_for("index"))
|
||||||
|
|
||||||
@app.route("/")
|
@app.route("/")
|
||||||
def index():
|
def index():
|
||||||
|
|
@ -115,5 +130,4 @@ def register():
|
||||||
return render_template("auth/register.html")
|
return render_template("auth/register.html")
|
||||||
|
|
||||||
if __name__ == '__main__':
|
if __name__ == '__main__':
|
||||||
register_admin_views()
|
|
||||||
app.run(debug=True)
|
app.run(debug=True)
|
||||||
|
|
@ -0,0 +1,79 @@
|
||||||
|
<!DOCTYPE html>
|
||||||
|
<html lang="en">
|
||||||
|
<head>
|
||||||
|
<meta charset="UTF-8">
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||||
|
<title>Admin Login</title>
|
||||||
|
<style>
|
||||||
|
body {
|
||||||
|
font-family: Arial, sans-serif;
|
||||||
|
margin: 0;
|
||||||
|
padding: 0;
|
||||||
|
display: flex;
|
||||||
|
justify-content: center;
|
||||||
|
align-items: center;
|
||||||
|
height: 100vh;
|
||||||
|
background-color: #f4f4f4;
|
||||||
|
}
|
||||||
|
|
||||||
|
form {
|
||||||
|
background-color: #fff;
|
||||||
|
padding: 20px;
|
||||||
|
border-radius: 8px;
|
||||||
|
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
|
||||||
|
width: 300px;
|
||||||
|
}
|
||||||
|
|
||||||
|
h2 {
|
||||||
|
margin-bottom: 20px;
|
||||||
|
}
|
||||||
|
|
||||||
|
label {
|
||||||
|
display: block;
|
||||||
|
margin-bottom: 10px;
|
||||||
|
}
|
||||||
|
|
||||||
|
input[type="text"],
|
||||||
|
input[type="password"] {
|
||||||
|
width: 100%;
|
||||||
|
padding: 8px;
|
||||||
|
margin-bottom: 10px;
|
||||||
|
border: 1px solid #ccc;
|
||||||
|
border-radius: 4px;
|
||||||
|
box-sizing: border-box;
|
||||||
|
}
|
||||||
|
|
||||||
|
input[type="submit"] {
|
||||||
|
background-color: #007bff;
|
||||||
|
color: #fff;
|
||||||
|
border: none;
|
||||||
|
padding: 10px 20px;
|
||||||
|
border-radius: 4px;
|
||||||
|
cursor: pointer;
|
||||||
|
font-size: 16px;
|
||||||
|
}
|
||||||
|
|
||||||
|
input[type="submit"]:hover {
|
||||||
|
background-color: #0056b3;
|
||||||
|
}
|
||||||
|
|
||||||
|
.error {
|
||||||
|
color: #ff0000;
|
||||||
|
margin-bottom: 10px;
|
||||||
|
}
|
||||||
|
</style>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<form method="post">
|
||||||
|
<h2>Admin Login</h2>
|
||||||
|
{% if error_msg %}
|
||||||
|
<p class="error">{{ error_msg }}</p>
|
||||||
|
{% endif %}
|
||||||
|
<label for="username">Username</label>
|
||||||
|
<input type="text" name="username" id="username" required>
|
||||||
|
<label for="password">Password</label>
|
||||||
|
<input type="password" name="password" id="password" required>
|
||||||
|
<input type="submit" value="Login">
|
||||||
|
</form>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
|
@ -0,0 +1,220 @@
|
||||||
|
# don't import any costly modules
|
||||||
|
import sys
|
||||||
|
import os
|
||||||
|
|
||||||
|
|
||||||
|
def warn_distutils_present():
|
||||||
|
if 'distutils' not in sys.modules:
|
||||||
|
return
|
||||||
|
import warnings
|
||||||
|
|
||||||
|
warnings.warn(
|
||||||
|
"Distutils was imported before Setuptools, but importing Setuptools "
|
||||||
|
"also replaces the `distutils` module in `sys.modules`. This may lead "
|
||||||
|
"to undesirable behaviors or errors. To avoid these issues, avoid "
|
||||||
|
"using distutils directly, ensure that setuptools is installed in the "
|
||||||
|
"traditional way (e.g. not an editable install), and/or make sure "
|
||||||
|
"that setuptools is always imported before distutils."
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def clear_distutils():
|
||||||
|
if 'distutils' not in sys.modules:
|
||||||
|
return
|
||||||
|
import warnings
|
||||||
|
|
||||||
|
warnings.warn("Setuptools is replacing distutils.")
|
||||||
|
mods = [
|
||||||
|
name
|
||||||
|
for name in sys.modules
|
||||||
|
if name == "distutils" or name.startswith("distutils.")
|
||||||
|
]
|
||||||
|
for name in mods:
|
||||||
|
del sys.modules[name]
|
||||||
|
|
||||||
|
|
||||||
|
def enabled():
|
||||||
|
"""
|
||||||
|
Allow selection of distutils by environment variable.
|
||||||
|
"""
|
||||||
|
which = os.environ.get('SETUPTOOLS_USE_DISTUTILS', 'local')
|
||||||
|
return which == 'local'
|
||||||
|
|
||||||
|
|
||||||
|
def ensure_local_distutils():
|
||||||
|
import importlib
|
||||||
|
|
||||||
|
clear_distutils()
|
||||||
|
|
||||||
|
# With the DistutilsMetaFinder in place,
|
||||||
|
# perform an import to cause distutils to be
|
||||||
|
# loaded from setuptools._distutils. Ref #2906.
|
||||||
|
with shim():
|
||||||
|
importlib.import_module('distutils')
|
||||||
|
|
||||||
|
# check that submodules load as expected
|
||||||
|
core = importlib.import_module('distutils.core')
|
||||||
|
assert '_distutils' in core.__file__, core.__file__
|
||||||
|
assert 'setuptools._distutils.log' not in sys.modules
|
||||||
|
|
||||||
|
|
||||||
|
def do_override():
|
||||||
|
"""
|
||||||
|
Ensure that the local copy of distutils is preferred over stdlib.
|
||||||
|
|
||||||
|
See https://github.com/pypa/setuptools/issues/417#issuecomment-392298401
|
||||||
|
for more motivation.
|
||||||
|
"""
|
||||||
|
if enabled():
|
||||||
|
warn_distutils_present()
|
||||||
|
ensure_local_distutils()
|
||||||
|
|
||||||
|
|
||||||
|
class _TrivialRe:
|
||||||
|
def __init__(self, *patterns):
|
||||||
|
self._patterns = patterns
|
||||||
|
|
||||||
|
def match(self, string):
|
||||||
|
return all(pat in string for pat in self._patterns)
|
||||||
|
|
||||||
|
|
||||||
|
class DistutilsMetaFinder:
|
||||||
|
def find_spec(self, fullname, path, target=None):
|
||||||
|
# optimization: only consider top level modules and those
|
||||||
|
# found in the CPython test suite.
|
||||||
|
if path is not None and not fullname.startswith('test.'):
|
||||||
|
return None
|
||||||
|
|
||||||
|
method_name = 'spec_for_{fullname}'.format(**locals())
|
||||||
|
method = getattr(self, method_name, lambda: None)
|
||||||
|
return method()
|
||||||
|
|
||||||
|
def spec_for_distutils(self):
|
||||||
|
if self.is_cpython():
|
||||||
|
return None
|
||||||
|
|
||||||
|
import importlib
|
||||||
|
import importlib.abc
|
||||||
|
import importlib.util
|
||||||
|
|
||||||
|
try:
|
||||||
|
mod = importlib.import_module('setuptools._distutils')
|
||||||
|
except Exception:
|
||||||
|
# There are a couple of cases where setuptools._distutils
|
||||||
|
# may not be present:
|
||||||
|
# - An older Setuptools without a local distutils is
|
||||||
|
# taking precedence. Ref #2957.
|
||||||
|
# - Path manipulation during sitecustomize removes
|
||||||
|
# setuptools from the path but only after the hook
|
||||||
|
# has been loaded. Ref #2980.
|
||||||
|
# In either case, fall back to stdlib behavior.
|
||||||
|
return None
|
||||||
|
|
||||||
|
class DistutilsLoader(importlib.abc.Loader):
|
||||||
|
def create_module(self, spec):
|
||||||
|
mod.__name__ = 'distutils'
|
||||||
|
return mod
|
||||||
|
|
||||||
|
def exec_module(self, module):
|
||||||
|
pass
|
||||||
|
|
||||||
|
return importlib.util.spec_from_loader(
|
||||||
|
'distutils', DistutilsLoader(), origin=mod.__file__
|
||||||
|
)
|
||||||
|
|
||||||
|
@staticmethod
|
||||||
|
def is_cpython():
|
||||||
|
"""
|
||||||
|
Suppress supplying distutils for CPython (build and tests).
|
||||||
|
Ref #2965 and #3007.
|
||||||
|
"""
|
||||||
|
return os.path.isfile('pybuilddir.txt')
|
||||||
|
|
||||||
|
def spec_for_pip(self):
|
||||||
|
"""
|
||||||
|
Ensure stdlib distutils when running under pip.
|
||||||
|
See pypa/pip#8761 for rationale.
|
||||||
|
"""
|
||||||
|
if sys.version_info >= (3, 12) or self.pip_imported_during_build():
|
||||||
|
return
|
||||||
|
clear_distutils()
|
||||||
|
self.spec_for_distutils = lambda: None
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
def pip_imported_during_build(cls):
|
||||||
|
"""
|
||||||
|
Detect if pip is being imported in a build script. Ref #2355.
|
||||||
|
"""
|
||||||
|
import traceback
|
||||||
|
|
||||||
|
return any(
|
||||||
|
cls.frame_file_is_setup(frame) for frame, line in traceback.walk_stack(None)
|
||||||
|
)
|
||||||
|
|
||||||
|
@staticmethod
|
||||||
|
def frame_file_is_setup(frame):
|
||||||
|
"""
|
||||||
|
Return True if the indicated frame suggests a setup.py file.
|
||||||
|
"""
|
||||||
|
# some frames may not have __file__ (#2940)
|
||||||
|
return frame.f_globals.get('__file__', '').endswith('setup.py')
|
||||||
|
|
||||||
|
def spec_for_sensitive_tests(self):
|
||||||
|
"""
|
||||||
|
Ensure stdlib distutils when running select tests under CPython.
|
||||||
|
|
||||||
|
python/cpython#91169
|
||||||
|
"""
|
||||||
|
clear_distutils()
|
||||||
|
self.spec_for_distutils = lambda: None
|
||||||
|
|
||||||
|
sensitive_tests = (
|
||||||
|
[
|
||||||
|
'test.test_distutils',
|
||||||
|
'test.test_peg_generator',
|
||||||
|
'test.test_importlib',
|
||||||
|
]
|
||||||
|
if sys.version_info < (3, 10)
|
||||||
|
else [
|
||||||
|
'test.test_distutils',
|
||||||
|
]
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
for name in DistutilsMetaFinder.sensitive_tests:
|
||||||
|
setattr(
|
||||||
|
DistutilsMetaFinder,
|
||||||
|
f'spec_for_{name}',
|
||||||
|
DistutilsMetaFinder.spec_for_sensitive_tests,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
DISTUTILS_FINDER = DistutilsMetaFinder()
|
||||||
|
|
||||||
|
|
||||||
|
def add_shim():
|
||||||
|
DISTUTILS_FINDER in sys.meta_path or insert_shim()
|
||||||
|
|
||||||
|
|
||||||
|
class shim:
|
||||||
|
def __enter__(self):
|
||||||
|
insert_shim()
|
||||||
|
|
||||||
|
def __exit__(self, exc, value, tb):
|
||||||
|
_remove_shim()
|
||||||
|
|
||||||
|
|
||||||
|
def insert_shim():
|
||||||
|
sys.meta_path.insert(0, DISTUTILS_FINDER)
|
||||||
|
|
||||||
|
|
||||||
|
def _remove_shim():
|
||||||
|
try:
|
||||||
|
sys.meta_path.remove(DISTUTILS_FINDER)
|
||||||
|
except ValueError:
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
if sys.version_info < (3, 12):
|
||||||
|
# DistutilsMetaFinder can only be disabled in Python < 3.12 (PEP 632)
|
||||||
|
remove_shim = _remove_shim
|
||||||
Binary file not shown.
Binary file not shown.
|
|
@ -0,0 +1 @@
|
||||||
|
__import__('_distutils_hack').do_override()
|
||||||
|
|
@ -0,0 +1 @@
|
||||||
|
import os; var = 'SETUPTOOLS_USE_DISTUTILS'; enabled = os.environ.get(var, 'local') == 'local'; enabled and __import__('_distutils_hack').add_shim();
|
||||||
File diff suppressed because it is too large
Load Diff
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,36 @@
|
||||||
|
"""Read resources contained within a package."""
|
||||||
|
|
||||||
|
from ._common import (
|
||||||
|
as_file,
|
||||||
|
files,
|
||||||
|
Package,
|
||||||
|
)
|
||||||
|
|
||||||
|
from ._legacy import (
|
||||||
|
contents,
|
||||||
|
open_binary,
|
||||||
|
read_binary,
|
||||||
|
open_text,
|
||||||
|
read_text,
|
||||||
|
is_resource,
|
||||||
|
path,
|
||||||
|
Resource,
|
||||||
|
)
|
||||||
|
|
||||||
|
from .abc import ResourceReader
|
||||||
|
|
||||||
|
|
||||||
|
__all__ = [
|
||||||
|
'Package',
|
||||||
|
'Resource',
|
||||||
|
'ResourceReader',
|
||||||
|
'as_file',
|
||||||
|
'contents',
|
||||||
|
'files',
|
||||||
|
'is_resource',
|
||||||
|
'open_binary',
|
||||||
|
'open_text',
|
||||||
|
'path',
|
||||||
|
'read_binary',
|
||||||
|
'read_text',
|
||||||
|
]
|
||||||
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
|
|
@ -0,0 +1,170 @@
|
||||||
|
from contextlib import suppress
|
||||||
|
from io import TextIOWrapper
|
||||||
|
|
||||||
|
from . import abc
|
||||||
|
|
||||||
|
|
||||||
|
class SpecLoaderAdapter:
|
||||||
|
"""
|
||||||
|
Adapt a package spec to adapt the underlying loader.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, spec, adapter=lambda spec: spec.loader):
|
||||||
|
self.spec = spec
|
||||||
|
self.loader = adapter(spec)
|
||||||
|
|
||||||
|
def __getattr__(self, name):
|
||||||
|
return getattr(self.spec, name)
|
||||||
|
|
||||||
|
|
||||||
|
class TraversableResourcesLoader:
|
||||||
|
"""
|
||||||
|
Adapt a loader to provide TraversableResources.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, spec):
|
||||||
|
self.spec = spec
|
||||||
|
|
||||||
|
def get_resource_reader(self, name):
|
||||||
|
return CompatibilityFiles(self.spec)._native()
|
||||||
|
|
||||||
|
|
||||||
|
def _io_wrapper(file, mode='r', *args, **kwargs):
|
||||||
|
if mode == 'r':
|
||||||
|
return TextIOWrapper(file, *args, **kwargs)
|
||||||
|
elif mode == 'rb':
|
||||||
|
return file
|
||||||
|
raise ValueError(
|
||||||
|
"Invalid mode value '{}', only 'r' and 'rb' are supported".format(mode)
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
class CompatibilityFiles:
|
||||||
|
"""
|
||||||
|
Adapter for an existing or non-existent resource reader
|
||||||
|
to provide a compatibility .files().
|
||||||
|
"""
|
||||||
|
|
||||||
|
class SpecPath(abc.Traversable):
|
||||||
|
"""
|
||||||
|
Path tied to a module spec.
|
||||||
|
Can be read and exposes the resource reader children.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, spec, reader):
|
||||||
|
self._spec = spec
|
||||||
|
self._reader = reader
|
||||||
|
|
||||||
|
def iterdir(self):
|
||||||
|
if not self._reader:
|
||||||
|
return iter(())
|
||||||
|
return iter(
|
||||||
|
CompatibilityFiles.ChildPath(self._reader, path)
|
||||||
|
for path in self._reader.contents()
|
||||||
|
)
|
||||||
|
|
||||||
|
def is_file(self):
|
||||||
|
return False
|
||||||
|
|
||||||
|
is_dir = is_file
|
||||||
|
|
||||||
|
def joinpath(self, other):
|
||||||
|
if not self._reader:
|
||||||
|
return CompatibilityFiles.OrphanPath(other)
|
||||||
|
return CompatibilityFiles.ChildPath(self._reader, other)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def name(self):
|
||||||
|
return self._spec.name
|
||||||
|
|
||||||
|
def open(self, mode='r', *args, **kwargs):
|
||||||
|
return _io_wrapper(self._reader.open_resource(None), mode, *args, **kwargs)
|
||||||
|
|
||||||
|
class ChildPath(abc.Traversable):
|
||||||
|
"""
|
||||||
|
Path tied to a resource reader child.
|
||||||
|
Can be read but doesn't expose any meaningful children.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, reader, name):
|
||||||
|
self._reader = reader
|
||||||
|
self._name = name
|
||||||
|
|
||||||
|
def iterdir(self):
|
||||||
|
return iter(())
|
||||||
|
|
||||||
|
def is_file(self):
|
||||||
|
return self._reader.is_resource(self.name)
|
||||||
|
|
||||||
|
def is_dir(self):
|
||||||
|
return not self.is_file()
|
||||||
|
|
||||||
|
def joinpath(self, other):
|
||||||
|
return CompatibilityFiles.OrphanPath(self.name, other)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def name(self):
|
||||||
|
return self._name
|
||||||
|
|
||||||
|
def open(self, mode='r', *args, **kwargs):
|
||||||
|
return _io_wrapper(
|
||||||
|
self._reader.open_resource(self.name), mode, *args, **kwargs
|
||||||
|
)
|
||||||
|
|
||||||
|
class OrphanPath(abc.Traversable):
|
||||||
|
"""
|
||||||
|
Orphan path, not tied to a module spec or resource reader.
|
||||||
|
Can't be read and doesn't expose any meaningful children.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, *path_parts):
|
||||||
|
if len(path_parts) < 1:
|
||||||
|
raise ValueError('Need at least one path part to construct a path')
|
||||||
|
self._path = path_parts
|
||||||
|
|
||||||
|
def iterdir(self):
|
||||||
|
return iter(())
|
||||||
|
|
||||||
|
def is_file(self):
|
||||||
|
return False
|
||||||
|
|
||||||
|
is_dir = is_file
|
||||||
|
|
||||||
|
def joinpath(self, other):
|
||||||
|
return CompatibilityFiles.OrphanPath(*self._path, other)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def name(self):
|
||||||
|
return self._path[-1]
|
||||||
|
|
||||||
|
def open(self, mode='r', *args, **kwargs):
|
||||||
|
raise FileNotFoundError("Can't open orphan path")
|
||||||
|
|
||||||
|
def __init__(self, spec):
|
||||||
|
self.spec = spec
|
||||||
|
|
||||||
|
@property
|
||||||
|
def _reader(self):
|
||||||
|
with suppress(AttributeError):
|
||||||
|
return self.spec.loader.get_resource_reader(self.spec.name)
|
||||||
|
|
||||||
|
def _native(self):
|
||||||
|
"""
|
||||||
|
Return the native reader if it supports files().
|
||||||
|
"""
|
||||||
|
reader = self._reader
|
||||||
|
return reader if hasattr(reader, 'files') else self
|
||||||
|
|
||||||
|
def __getattr__(self, attr):
|
||||||
|
return getattr(self._reader, attr)
|
||||||
|
|
||||||
|
def files(self):
|
||||||
|
return CompatibilityFiles.SpecPath(self.spec, self._reader)
|
||||||
|
|
||||||
|
|
||||||
|
def wrap_spec(package):
|
||||||
|
"""
|
||||||
|
Construct a package spec with traversable compatibility
|
||||||
|
on the spec/loader/reader.
|
||||||
|
"""
|
||||||
|
return SpecLoaderAdapter(package.__spec__, TraversableResourcesLoader)
|
||||||
|
|
@ -0,0 +1,207 @@
|
||||||
|
import os
|
||||||
|
import pathlib
|
||||||
|
import tempfile
|
||||||
|
import functools
|
||||||
|
import contextlib
|
||||||
|
import types
|
||||||
|
import importlib
|
||||||
|
import inspect
|
||||||
|
import warnings
|
||||||
|
import itertools
|
||||||
|
|
||||||
|
from typing import Union, Optional, cast
|
||||||
|
from .abc import ResourceReader, Traversable
|
||||||
|
|
||||||
|
from ._compat import wrap_spec
|
||||||
|
|
||||||
|
Package = Union[types.ModuleType, str]
|
||||||
|
Anchor = Package
|
||||||
|
|
||||||
|
|
||||||
|
def package_to_anchor(func):
|
||||||
|
"""
|
||||||
|
Replace 'package' parameter as 'anchor' and warn about the change.
|
||||||
|
|
||||||
|
Other errors should fall through.
|
||||||
|
|
||||||
|
>>> files('a', 'b')
|
||||||
|
Traceback (most recent call last):
|
||||||
|
TypeError: files() takes from 0 to 1 positional arguments but 2 were given
|
||||||
|
"""
|
||||||
|
undefined = object()
|
||||||
|
|
||||||
|
@functools.wraps(func)
|
||||||
|
def wrapper(anchor=undefined, package=undefined):
|
||||||
|
if package is not undefined:
|
||||||
|
if anchor is not undefined:
|
||||||
|
return func(anchor, package)
|
||||||
|
warnings.warn(
|
||||||
|
"First parameter to files is renamed to 'anchor'",
|
||||||
|
DeprecationWarning,
|
||||||
|
stacklevel=2,
|
||||||
|
)
|
||||||
|
return func(package)
|
||||||
|
elif anchor is undefined:
|
||||||
|
return func()
|
||||||
|
return func(anchor)
|
||||||
|
|
||||||
|
return wrapper
|
||||||
|
|
||||||
|
|
||||||
|
@package_to_anchor
|
||||||
|
def files(anchor: Optional[Anchor] = None) -> Traversable:
|
||||||
|
"""
|
||||||
|
Get a Traversable resource for an anchor.
|
||||||
|
"""
|
||||||
|
return from_package(resolve(anchor))
|
||||||
|
|
||||||
|
|
||||||
|
def get_resource_reader(package: types.ModuleType) -> Optional[ResourceReader]:
|
||||||
|
"""
|
||||||
|
Return the package's loader if it's a ResourceReader.
|
||||||
|
"""
|
||||||
|
# We can't use
|
||||||
|
# a issubclass() check here because apparently abc.'s __subclasscheck__()
|
||||||
|
# hook wants to create a weak reference to the object, but
|
||||||
|
# zipimport.zipimporter does not support weak references, resulting in a
|
||||||
|
# TypeError. That seems terrible.
|
||||||
|
spec = package.__spec__
|
||||||
|
reader = getattr(spec.loader, 'get_resource_reader', None) # type: ignore
|
||||||
|
if reader is None:
|
||||||
|
return None
|
||||||
|
return reader(spec.name) # type: ignore
|
||||||
|
|
||||||
|
|
||||||
|
@functools.singledispatch
|
||||||
|
def resolve(cand: Optional[Anchor]) -> types.ModuleType:
|
||||||
|
return cast(types.ModuleType, cand)
|
||||||
|
|
||||||
|
|
||||||
|
@resolve.register
|
||||||
|
def _(cand: str) -> types.ModuleType:
|
||||||
|
return importlib.import_module(cand)
|
||||||
|
|
||||||
|
|
||||||
|
@resolve.register
|
||||||
|
def _(cand: None) -> types.ModuleType:
|
||||||
|
return resolve(_infer_caller().f_globals['__name__'])
|
||||||
|
|
||||||
|
|
||||||
|
def _infer_caller():
|
||||||
|
"""
|
||||||
|
Walk the stack and find the frame of the first caller not in this module.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def is_this_file(frame_info):
|
||||||
|
return frame_info.filename == __file__
|
||||||
|
|
||||||
|
def is_wrapper(frame_info):
|
||||||
|
return frame_info.function == 'wrapper'
|
||||||
|
|
||||||
|
not_this_file = itertools.filterfalse(is_this_file, inspect.stack())
|
||||||
|
# also exclude 'wrapper' due to singledispatch in the call stack
|
||||||
|
callers = itertools.filterfalse(is_wrapper, not_this_file)
|
||||||
|
return next(callers).frame
|
||||||
|
|
||||||
|
|
||||||
|
def from_package(package: types.ModuleType):
|
||||||
|
"""
|
||||||
|
Return a Traversable object for the given package.
|
||||||
|
|
||||||
|
"""
|
||||||
|
spec = wrap_spec(package)
|
||||||
|
reader = spec.loader.get_resource_reader(spec.name)
|
||||||
|
return reader.files()
|
||||||
|
|
||||||
|
|
||||||
|
@contextlib.contextmanager
|
||||||
|
def _tempfile(
|
||||||
|
reader,
|
||||||
|
suffix='',
|
||||||
|
# gh-93353: Keep a reference to call os.remove() in late Python
|
||||||
|
# finalization.
|
||||||
|
*,
|
||||||
|
_os_remove=os.remove,
|
||||||
|
):
|
||||||
|
# Not using tempfile.NamedTemporaryFile as it leads to deeper 'try'
|
||||||
|
# blocks due to the need to close the temporary file to work on Windows
|
||||||
|
# properly.
|
||||||
|
fd, raw_path = tempfile.mkstemp(suffix=suffix)
|
||||||
|
try:
|
||||||
|
try:
|
||||||
|
os.write(fd, reader())
|
||||||
|
finally:
|
||||||
|
os.close(fd)
|
||||||
|
del reader
|
||||||
|
yield pathlib.Path(raw_path)
|
||||||
|
finally:
|
||||||
|
try:
|
||||||
|
_os_remove(raw_path)
|
||||||
|
except FileNotFoundError:
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
def _temp_file(path):
|
||||||
|
return _tempfile(path.read_bytes, suffix=path.name)
|
||||||
|
|
||||||
|
|
||||||
|
def _is_present_dir(path: Traversable) -> bool:
|
||||||
|
"""
|
||||||
|
Some Traversables implement ``is_dir()`` to raise an
|
||||||
|
exception (i.e. ``FileNotFoundError``) when the
|
||||||
|
directory doesn't exist. This function wraps that call
|
||||||
|
to always return a boolean and only return True
|
||||||
|
if there's a dir and it exists.
|
||||||
|
"""
|
||||||
|
with contextlib.suppress(FileNotFoundError):
|
||||||
|
return path.is_dir()
|
||||||
|
return False
|
||||||
|
|
||||||
|
|
||||||
|
@functools.singledispatch
|
||||||
|
def as_file(path):
|
||||||
|
"""
|
||||||
|
Given a Traversable object, return that object as a
|
||||||
|
path on the local file system in a context manager.
|
||||||
|
"""
|
||||||
|
return _temp_dir(path) if _is_present_dir(path) else _temp_file(path)
|
||||||
|
|
||||||
|
|
||||||
|
@as_file.register(pathlib.Path)
|
||||||
|
@contextlib.contextmanager
|
||||||
|
def _(path):
|
||||||
|
"""
|
||||||
|
Degenerate behavior for pathlib.Path objects.
|
||||||
|
"""
|
||||||
|
yield path
|
||||||
|
|
||||||
|
|
||||||
|
@contextlib.contextmanager
|
||||||
|
def _temp_path(dir: tempfile.TemporaryDirectory):
|
||||||
|
"""
|
||||||
|
Wrap tempfile.TemporyDirectory to return a pathlib object.
|
||||||
|
"""
|
||||||
|
with dir as result:
|
||||||
|
yield pathlib.Path(result)
|
||||||
|
|
||||||
|
|
||||||
|
@contextlib.contextmanager
|
||||||
|
def _temp_dir(path):
|
||||||
|
"""
|
||||||
|
Given a traversable dir, recursively replicate the whole tree
|
||||||
|
to the file system in a context manager.
|
||||||
|
"""
|
||||||
|
assert path.is_dir()
|
||||||
|
with _temp_path(tempfile.TemporaryDirectory()) as temp_dir:
|
||||||
|
yield _write_contents(temp_dir, path)
|
||||||
|
|
||||||
|
|
||||||
|
def _write_contents(target, source):
|
||||||
|
child = target.joinpath(source.name)
|
||||||
|
if source.is_dir():
|
||||||
|
child.mkdir()
|
||||||
|
for item in source.iterdir():
|
||||||
|
_write_contents(child, item)
|
||||||
|
else:
|
||||||
|
child.write_bytes(source.read_bytes())
|
||||||
|
return child
|
||||||
|
|
@ -0,0 +1,108 @@
|
||||||
|
# flake8: noqa
|
||||||
|
|
||||||
|
import abc
|
||||||
|
import os
|
||||||
|
import sys
|
||||||
|
import pathlib
|
||||||
|
from contextlib import suppress
|
||||||
|
from typing import Union
|
||||||
|
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 10):
|
||||||
|
from zipfile import Path as ZipPath # type: ignore
|
||||||
|
else:
|
||||||
|
from ..zipp import Path as ZipPath # type: ignore
|
||||||
|
|
||||||
|
|
||||||
|
try:
|
||||||
|
from typing import runtime_checkable # type: ignore
|
||||||
|
except ImportError:
|
||||||
|
|
||||||
|
def runtime_checkable(cls): # type: ignore
|
||||||
|
return cls
|
||||||
|
|
||||||
|
|
||||||
|
try:
|
||||||
|
from typing import Protocol # type: ignore
|
||||||
|
except ImportError:
|
||||||
|
Protocol = abc.ABC # type: ignore
|
||||||
|
|
||||||
|
|
||||||
|
class TraversableResourcesLoader:
|
||||||
|
"""
|
||||||
|
Adapt loaders to provide TraversableResources and other
|
||||||
|
compatibility.
|
||||||
|
|
||||||
|
Used primarily for Python 3.9 and earlier where the native
|
||||||
|
loaders do not yet implement TraversableResources.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, spec):
|
||||||
|
self.spec = spec
|
||||||
|
|
||||||
|
@property
|
||||||
|
def path(self):
|
||||||
|
return self.spec.origin
|
||||||
|
|
||||||
|
def get_resource_reader(self, name):
|
||||||
|
from . import readers, _adapters
|
||||||
|
|
||||||
|
def _zip_reader(spec):
|
||||||
|
with suppress(AttributeError):
|
||||||
|
return readers.ZipReader(spec.loader, spec.name)
|
||||||
|
|
||||||
|
def _namespace_reader(spec):
|
||||||
|
with suppress(AttributeError, ValueError):
|
||||||
|
return readers.NamespaceReader(spec.submodule_search_locations)
|
||||||
|
|
||||||
|
def _available_reader(spec):
|
||||||
|
with suppress(AttributeError):
|
||||||
|
return spec.loader.get_resource_reader(spec.name)
|
||||||
|
|
||||||
|
def _native_reader(spec):
|
||||||
|
reader = _available_reader(spec)
|
||||||
|
return reader if hasattr(reader, 'files') else None
|
||||||
|
|
||||||
|
def _file_reader(spec):
|
||||||
|
try:
|
||||||
|
path = pathlib.Path(self.path)
|
||||||
|
except TypeError:
|
||||||
|
return None
|
||||||
|
if path.exists():
|
||||||
|
return readers.FileReader(self)
|
||||||
|
|
||||||
|
return (
|
||||||
|
# native reader if it supplies 'files'
|
||||||
|
_native_reader(self.spec)
|
||||||
|
or
|
||||||
|
# local ZipReader if a zip module
|
||||||
|
_zip_reader(self.spec)
|
||||||
|
or
|
||||||
|
# local NamespaceReader if a namespace module
|
||||||
|
_namespace_reader(self.spec)
|
||||||
|
or
|
||||||
|
# local FileReader
|
||||||
|
_file_reader(self.spec)
|
||||||
|
# fallback - adapt the spec ResourceReader to TraversableReader
|
||||||
|
or _adapters.CompatibilityFiles(self.spec)
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def wrap_spec(package):
|
||||||
|
"""
|
||||||
|
Construct a package spec with traversable compatibility
|
||||||
|
on the spec/loader/reader.
|
||||||
|
|
||||||
|
Supersedes _adapters.wrap_spec to use TraversableResourcesLoader
|
||||||
|
from above for older Python compatibility (<3.10).
|
||||||
|
"""
|
||||||
|
from . import _adapters
|
||||||
|
|
||||||
|
return _adapters.SpecLoaderAdapter(package.__spec__, TraversableResourcesLoader)
|
||||||
|
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 9):
|
||||||
|
StrPath = Union[str, os.PathLike[str]]
|
||||||
|
else:
|
||||||
|
# PathLike is only subscriptable at runtime in 3.9+
|
||||||
|
StrPath = Union[str, "os.PathLike[str]"]
|
||||||
|
|
@ -0,0 +1,35 @@
|
||||||
|
from itertools import filterfalse
|
||||||
|
|
||||||
|
from typing import (
|
||||||
|
Callable,
|
||||||
|
Iterable,
|
||||||
|
Iterator,
|
||||||
|
Optional,
|
||||||
|
Set,
|
||||||
|
TypeVar,
|
||||||
|
Union,
|
||||||
|
)
|
||||||
|
|
||||||
|
# Type and type variable definitions
|
||||||
|
_T = TypeVar('_T')
|
||||||
|
_U = TypeVar('_U')
|
||||||
|
|
||||||
|
|
||||||
|
def unique_everseen(
|
||||||
|
iterable: Iterable[_T], key: Optional[Callable[[_T], _U]] = None
|
||||||
|
) -> Iterator[_T]:
|
||||||
|
"List unique elements, preserving order. Remember all elements ever seen."
|
||||||
|
# unique_everseen('AAAABBBCCDAABBB') --> A B C D
|
||||||
|
# unique_everseen('ABBCcAD', str.lower) --> A B C D
|
||||||
|
seen: Set[Union[_T, _U]] = set()
|
||||||
|
seen_add = seen.add
|
||||||
|
if key is None:
|
||||||
|
for element in filterfalse(seen.__contains__, iterable):
|
||||||
|
seen_add(element)
|
||||||
|
yield element
|
||||||
|
else:
|
||||||
|
for element in iterable:
|
||||||
|
k = key(element)
|
||||||
|
if k not in seen:
|
||||||
|
seen_add(k)
|
||||||
|
yield element
|
||||||
|
|
@ -0,0 +1,120 @@
|
||||||
|
import functools
|
||||||
|
import os
|
||||||
|
import pathlib
|
||||||
|
import types
|
||||||
|
import warnings
|
||||||
|
|
||||||
|
from typing import Union, Iterable, ContextManager, BinaryIO, TextIO, Any
|
||||||
|
|
||||||
|
from . import _common
|
||||||
|
|
||||||
|
Package = Union[types.ModuleType, str]
|
||||||
|
Resource = str
|
||||||
|
|
||||||
|
|
||||||
|
def deprecated(func):
|
||||||
|
@functools.wraps(func)
|
||||||
|
def wrapper(*args, **kwargs):
|
||||||
|
warnings.warn(
|
||||||
|
f"{func.__name__} is deprecated. Use files() instead. "
|
||||||
|
"Refer to https://importlib-resources.readthedocs.io"
|
||||||
|
"/en/latest/using.html#migrating-from-legacy for migration advice.",
|
||||||
|
DeprecationWarning,
|
||||||
|
stacklevel=2,
|
||||||
|
)
|
||||||
|
return func(*args, **kwargs)
|
||||||
|
|
||||||
|
return wrapper
|
||||||
|
|
||||||
|
|
||||||
|
def normalize_path(path: Any) -> str:
|
||||||
|
"""Normalize a path by ensuring it is a string.
|
||||||
|
|
||||||
|
If the resulting string contains path separators, an exception is raised.
|
||||||
|
"""
|
||||||
|
str_path = str(path)
|
||||||
|
parent, file_name = os.path.split(str_path)
|
||||||
|
if parent:
|
||||||
|
raise ValueError(f'{path!r} must be only a file name')
|
||||||
|
return file_name
|
||||||
|
|
||||||
|
|
||||||
|
@deprecated
|
||||||
|
def open_binary(package: Package, resource: Resource) -> BinaryIO:
|
||||||
|
"""Return a file-like object opened for binary reading of the resource."""
|
||||||
|
return (_common.files(package) / normalize_path(resource)).open('rb')
|
||||||
|
|
||||||
|
|
||||||
|
@deprecated
|
||||||
|
def read_binary(package: Package, resource: Resource) -> bytes:
|
||||||
|
"""Return the binary contents of the resource."""
|
||||||
|
return (_common.files(package) / normalize_path(resource)).read_bytes()
|
||||||
|
|
||||||
|
|
||||||
|
@deprecated
|
||||||
|
def open_text(
|
||||||
|
package: Package,
|
||||||
|
resource: Resource,
|
||||||
|
encoding: str = 'utf-8',
|
||||||
|
errors: str = 'strict',
|
||||||
|
) -> TextIO:
|
||||||
|
"""Return a file-like object opened for text reading of the resource."""
|
||||||
|
return (_common.files(package) / normalize_path(resource)).open(
|
||||||
|
'r', encoding=encoding, errors=errors
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
@deprecated
|
||||||
|
def read_text(
|
||||||
|
package: Package,
|
||||||
|
resource: Resource,
|
||||||
|
encoding: str = 'utf-8',
|
||||||
|
errors: str = 'strict',
|
||||||
|
) -> str:
|
||||||
|
"""Return the decoded string of the resource.
|
||||||
|
|
||||||
|
The decoding-related arguments have the same semantics as those of
|
||||||
|
bytes.decode().
|
||||||
|
"""
|
||||||
|
with open_text(package, resource, encoding, errors) as fp:
|
||||||
|
return fp.read()
|
||||||
|
|
||||||
|
|
||||||
|
@deprecated
|
||||||
|
def contents(package: Package) -> Iterable[str]:
|
||||||
|
"""Return an iterable of entries in `package`.
|
||||||
|
|
||||||
|
Note that not all entries are resources. Specifically, directories are
|
||||||
|
not considered resources. Use `is_resource()` on each entry returned here
|
||||||
|
to check if it is a resource or not.
|
||||||
|
"""
|
||||||
|
return [path.name for path in _common.files(package).iterdir()]
|
||||||
|
|
||||||
|
|
||||||
|
@deprecated
|
||||||
|
def is_resource(package: Package, name: str) -> bool:
|
||||||
|
"""True if `name` is a resource inside `package`.
|
||||||
|
|
||||||
|
Directories are *not* resources.
|
||||||
|
"""
|
||||||
|
resource = normalize_path(name)
|
||||||
|
return any(
|
||||||
|
traversable.name == resource and traversable.is_file()
|
||||||
|
for traversable in _common.files(package).iterdir()
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
@deprecated
|
||||||
|
def path(
|
||||||
|
package: Package,
|
||||||
|
resource: Resource,
|
||||||
|
) -> ContextManager[pathlib.Path]:
|
||||||
|
"""A context manager providing a file path object to the resource.
|
||||||
|
|
||||||
|
If the resource does not already exist on its own on the file system,
|
||||||
|
a temporary file will be created. If the file was created, the file
|
||||||
|
will be deleted upon exiting the context manager (no exception is
|
||||||
|
raised if the file was deleted prior to the context manager
|
||||||
|
exiting).
|
||||||
|
"""
|
||||||
|
return _common.as_file(_common.files(package) / normalize_path(resource))
|
||||||
|
|
@ -0,0 +1,170 @@
|
||||||
|
import abc
|
||||||
|
import io
|
||||||
|
import itertools
|
||||||
|
import pathlib
|
||||||
|
from typing import Any, BinaryIO, Iterable, Iterator, NoReturn, Text, Optional
|
||||||
|
|
||||||
|
from ._compat import runtime_checkable, Protocol, StrPath
|
||||||
|
|
||||||
|
|
||||||
|
__all__ = ["ResourceReader", "Traversable", "TraversableResources"]
|
||||||
|
|
||||||
|
|
||||||
|
class ResourceReader(metaclass=abc.ABCMeta):
|
||||||
|
"""Abstract base class for loaders to provide resource reading support."""
|
||||||
|
|
||||||
|
@abc.abstractmethod
|
||||||
|
def open_resource(self, resource: Text) -> BinaryIO:
|
||||||
|
"""Return an opened, file-like object for binary reading.
|
||||||
|
|
||||||
|
The 'resource' argument is expected to represent only a file name.
|
||||||
|
If the resource cannot be found, FileNotFoundError is raised.
|
||||||
|
"""
|
||||||
|
# This deliberately raises FileNotFoundError instead of
|
||||||
|
# NotImplementedError so that if this method is accidentally called,
|
||||||
|
# it'll still do the right thing.
|
||||||
|
raise FileNotFoundError
|
||||||
|
|
||||||
|
@abc.abstractmethod
|
||||||
|
def resource_path(self, resource: Text) -> Text:
|
||||||
|
"""Return the file system path to the specified resource.
|
||||||
|
|
||||||
|
The 'resource' argument is expected to represent only a file name.
|
||||||
|
If the resource does not exist on the file system, raise
|
||||||
|
FileNotFoundError.
|
||||||
|
"""
|
||||||
|
# This deliberately raises FileNotFoundError instead of
|
||||||
|
# NotImplementedError so that if this method is accidentally called,
|
||||||
|
# it'll still do the right thing.
|
||||||
|
raise FileNotFoundError
|
||||||
|
|
||||||
|
@abc.abstractmethod
|
||||||
|
def is_resource(self, path: Text) -> bool:
|
||||||
|
"""Return True if the named 'path' is a resource.
|
||||||
|
|
||||||
|
Files are resources, directories are not.
|
||||||
|
"""
|
||||||
|
raise FileNotFoundError
|
||||||
|
|
||||||
|
@abc.abstractmethod
|
||||||
|
def contents(self) -> Iterable[str]:
|
||||||
|
"""Return an iterable of entries in `package`."""
|
||||||
|
raise FileNotFoundError
|
||||||
|
|
||||||
|
|
||||||
|
class TraversalError(Exception):
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
@runtime_checkable
|
||||||
|
class Traversable(Protocol):
|
||||||
|
"""
|
||||||
|
An object with a subset of pathlib.Path methods suitable for
|
||||||
|
traversing directories and opening files.
|
||||||
|
|
||||||
|
Any exceptions that occur when accessing the backing resource
|
||||||
|
may propagate unaltered.
|
||||||
|
"""
|
||||||
|
|
||||||
|
@abc.abstractmethod
|
||||||
|
def iterdir(self) -> Iterator["Traversable"]:
|
||||||
|
"""
|
||||||
|
Yield Traversable objects in self
|
||||||
|
"""
|
||||||
|
|
||||||
|
def read_bytes(self) -> bytes:
|
||||||
|
"""
|
||||||
|
Read contents of self as bytes
|
||||||
|
"""
|
||||||
|
with self.open('rb') as strm:
|
||||||
|
return strm.read()
|
||||||
|
|
||||||
|
def read_text(self, encoding: Optional[str] = None) -> str:
|
||||||
|
"""
|
||||||
|
Read contents of self as text
|
||||||
|
"""
|
||||||
|
with self.open(encoding=encoding) as strm:
|
||||||
|
return strm.read()
|
||||||
|
|
||||||
|
@abc.abstractmethod
|
||||||
|
def is_dir(self) -> bool:
|
||||||
|
"""
|
||||||
|
Return True if self is a directory
|
||||||
|
"""
|
||||||
|
|
||||||
|
@abc.abstractmethod
|
||||||
|
def is_file(self) -> bool:
|
||||||
|
"""
|
||||||
|
Return True if self is a file
|
||||||
|
"""
|
||||||
|
|
||||||
|
def joinpath(self, *descendants: StrPath) -> "Traversable":
|
||||||
|
"""
|
||||||
|
Return Traversable resolved with any descendants applied.
|
||||||
|
|
||||||
|
Each descendant should be a path segment relative to self
|
||||||
|
and each may contain multiple levels separated by
|
||||||
|
``posixpath.sep`` (``/``).
|
||||||
|
"""
|
||||||
|
if not descendants:
|
||||||
|
return self
|
||||||
|
names = itertools.chain.from_iterable(
|
||||||
|
path.parts for path in map(pathlib.PurePosixPath, descendants)
|
||||||
|
)
|
||||||
|
target = next(names)
|
||||||
|
matches = (
|
||||||
|
traversable for traversable in self.iterdir() if traversable.name == target
|
||||||
|
)
|
||||||
|
try:
|
||||||
|
match = next(matches)
|
||||||
|
except StopIteration:
|
||||||
|
raise TraversalError(
|
||||||
|
"Target not found during traversal.", target, list(names)
|
||||||
|
)
|
||||||
|
return match.joinpath(*names)
|
||||||
|
|
||||||
|
def __truediv__(self, child: StrPath) -> "Traversable":
|
||||||
|
"""
|
||||||
|
Return Traversable child in self
|
||||||
|
"""
|
||||||
|
return self.joinpath(child)
|
||||||
|
|
||||||
|
@abc.abstractmethod
|
||||||
|
def open(self, mode='r', *args, **kwargs):
|
||||||
|
"""
|
||||||
|
mode may be 'r' or 'rb' to open as text or binary. Return a handle
|
||||||
|
suitable for reading (same as pathlib.Path.open).
|
||||||
|
|
||||||
|
When opening as text, accepts encoding parameters such as those
|
||||||
|
accepted by io.TextIOWrapper.
|
||||||
|
"""
|
||||||
|
|
||||||
|
@property
|
||||||
|
@abc.abstractmethod
|
||||||
|
def name(self) -> str:
|
||||||
|
"""
|
||||||
|
The base name of this object without any parent references.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class TraversableResources(ResourceReader):
|
||||||
|
"""
|
||||||
|
The required interface for providing traversable
|
||||||
|
resources.
|
||||||
|
"""
|
||||||
|
|
||||||
|
@abc.abstractmethod
|
||||||
|
def files(self) -> "Traversable":
|
||||||
|
"""Return a Traversable object for the loaded package."""
|
||||||
|
|
||||||
|
def open_resource(self, resource: StrPath) -> io.BufferedReader:
|
||||||
|
return self.files().joinpath(resource).open('rb')
|
||||||
|
|
||||||
|
def resource_path(self, resource: Any) -> NoReturn:
|
||||||
|
raise FileNotFoundError(resource)
|
||||||
|
|
||||||
|
def is_resource(self, path: StrPath) -> bool:
|
||||||
|
return self.files().joinpath(path).is_file()
|
||||||
|
|
||||||
|
def contents(self) -> Iterator[str]:
|
||||||
|
return (item.name for item in self.files().iterdir())
|
||||||
|
|
@ -0,0 +1,120 @@
|
||||||
|
import collections
|
||||||
|
import pathlib
|
||||||
|
import operator
|
||||||
|
|
||||||
|
from . import abc
|
||||||
|
|
||||||
|
from ._itertools import unique_everseen
|
||||||
|
from ._compat import ZipPath
|
||||||
|
|
||||||
|
|
||||||
|
def remove_duplicates(items):
|
||||||
|
return iter(collections.OrderedDict.fromkeys(items))
|
||||||
|
|
||||||
|
|
||||||
|
class FileReader(abc.TraversableResources):
|
||||||
|
def __init__(self, loader):
|
||||||
|
self.path = pathlib.Path(loader.path).parent
|
||||||
|
|
||||||
|
def resource_path(self, resource):
|
||||||
|
"""
|
||||||
|
Return the file system path to prevent
|
||||||
|
`resources.path()` from creating a temporary
|
||||||
|
copy.
|
||||||
|
"""
|
||||||
|
return str(self.path.joinpath(resource))
|
||||||
|
|
||||||
|
def files(self):
|
||||||
|
return self.path
|
||||||
|
|
||||||
|
|
||||||
|
class ZipReader(abc.TraversableResources):
|
||||||
|
def __init__(self, loader, module):
|
||||||
|
_, _, name = module.rpartition('.')
|
||||||
|
self.prefix = loader.prefix.replace('\\', '/') + name + '/'
|
||||||
|
self.archive = loader.archive
|
||||||
|
|
||||||
|
def open_resource(self, resource):
|
||||||
|
try:
|
||||||
|
return super().open_resource(resource)
|
||||||
|
except KeyError as exc:
|
||||||
|
raise FileNotFoundError(exc.args[0])
|
||||||
|
|
||||||
|
def is_resource(self, path):
|
||||||
|
# workaround for `zipfile.Path.is_file` returning true
|
||||||
|
# for non-existent paths.
|
||||||
|
target = self.files().joinpath(path)
|
||||||
|
return target.is_file() and target.exists()
|
||||||
|
|
||||||
|
def files(self):
|
||||||
|
return ZipPath(self.archive, self.prefix)
|
||||||
|
|
||||||
|
|
||||||
|
class MultiplexedPath(abc.Traversable):
|
||||||
|
"""
|
||||||
|
Given a series of Traversable objects, implement a merged
|
||||||
|
version of the interface across all objects. Useful for
|
||||||
|
namespace packages which may be multihomed at a single
|
||||||
|
name.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, *paths):
|
||||||
|
self._paths = list(map(pathlib.Path, remove_duplicates(paths)))
|
||||||
|
if not self._paths:
|
||||||
|
message = 'MultiplexedPath must contain at least one path'
|
||||||
|
raise FileNotFoundError(message)
|
||||||
|
if not all(path.is_dir() for path in self._paths):
|
||||||
|
raise NotADirectoryError('MultiplexedPath only supports directories')
|
||||||
|
|
||||||
|
def iterdir(self):
|
||||||
|
files = (file for path in self._paths for file in path.iterdir())
|
||||||
|
return unique_everseen(files, key=operator.attrgetter('name'))
|
||||||
|
|
||||||
|
def read_bytes(self):
|
||||||
|
raise FileNotFoundError(f'{self} is not a file')
|
||||||
|
|
||||||
|
def read_text(self, *args, **kwargs):
|
||||||
|
raise FileNotFoundError(f'{self} is not a file')
|
||||||
|
|
||||||
|
def is_dir(self):
|
||||||
|
return True
|
||||||
|
|
||||||
|
def is_file(self):
|
||||||
|
return False
|
||||||
|
|
||||||
|
def joinpath(self, *descendants):
|
||||||
|
try:
|
||||||
|
return super().joinpath(*descendants)
|
||||||
|
except abc.TraversalError:
|
||||||
|
# One of the paths did not resolve (a directory does not exist).
|
||||||
|
# Just return something that will not exist.
|
||||||
|
return self._paths[0].joinpath(*descendants)
|
||||||
|
|
||||||
|
def open(self, *args, **kwargs):
|
||||||
|
raise FileNotFoundError(f'{self} is not a file')
|
||||||
|
|
||||||
|
@property
|
||||||
|
def name(self):
|
||||||
|
return self._paths[0].name
|
||||||
|
|
||||||
|
def __repr__(self):
|
||||||
|
paths = ', '.join(f"'{path}'" for path in self._paths)
|
||||||
|
return f'MultiplexedPath({paths})'
|
||||||
|
|
||||||
|
|
||||||
|
class NamespaceReader(abc.TraversableResources):
|
||||||
|
def __init__(self, namespace_path):
|
||||||
|
if 'NamespacePath' not in str(namespace_path):
|
||||||
|
raise ValueError('Invalid path')
|
||||||
|
self.path = MultiplexedPath(*list(namespace_path))
|
||||||
|
|
||||||
|
def resource_path(self, resource):
|
||||||
|
"""
|
||||||
|
Return the file system path to prevent
|
||||||
|
`resources.path()` from creating a temporary
|
||||||
|
copy.
|
||||||
|
"""
|
||||||
|
return str(self.path.joinpath(resource))
|
||||||
|
|
||||||
|
def files(self):
|
||||||
|
return self.path
|
||||||
|
|
@ -0,0 +1,106 @@
|
||||||
|
"""
|
||||||
|
Interface adapters for low-level readers.
|
||||||
|
"""
|
||||||
|
|
||||||
|
import abc
|
||||||
|
import io
|
||||||
|
import itertools
|
||||||
|
from typing import BinaryIO, List
|
||||||
|
|
||||||
|
from .abc import Traversable, TraversableResources
|
||||||
|
|
||||||
|
|
||||||
|
class SimpleReader(abc.ABC):
|
||||||
|
"""
|
||||||
|
The minimum, low-level interface required from a resource
|
||||||
|
provider.
|
||||||
|
"""
|
||||||
|
|
||||||
|
@property
|
||||||
|
@abc.abstractmethod
|
||||||
|
def package(self) -> str:
|
||||||
|
"""
|
||||||
|
The name of the package for which this reader loads resources.
|
||||||
|
"""
|
||||||
|
|
||||||
|
@abc.abstractmethod
|
||||||
|
def children(self) -> List['SimpleReader']:
|
||||||
|
"""
|
||||||
|
Obtain an iterable of SimpleReader for available
|
||||||
|
child containers (e.g. directories).
|
||||||
|
"""
|
||||||
|
|
||||||
|
@abc.abstractmethod
|
||||||
|
def resources(self) -> List[str]:
|
||||||
|
"""
|
||||||
|
Obtain available named resources for this virtual package.
|
||||||
|
"""
|
||||||
|
|
||||||
|
@abc.abstractmethod
|
||||||
|
def open_binary(self, resource: str) -> BinaryIO:
|
||||||
|
"""
|
||||||
|
Obtain a File-like for a named resource.
|
||||||
|
"""
|
||||||
|
|
||||||
|
@property
|
||||||
|
def name(self):
|
||||||
|
return self.package.split('.')[-1]
|
||||||
|
|
||||||
|
|
||||||
|
class ResourceContainer(Traversable):
|
||||||
|
"""
|
||||||
|
Traversable container for a package's resources via its reader.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, reader: SimpleReader):
|
||||||
|
self.reader = reader
|
||||||
|
|
||||||
|
def is_dir(self):
|
||||||
|
return True
|
||||||
|
|
||||||
|
def is_file(self):
|
||||||
|
return False
|
||||||
|
|
||||||
|
def iterdir(self):
|
||||||
|
files = (ResourceHandle(self, name) for name in self.reader.resources)
|
||||||
|
dirs = map(ResourceContainer, self.reader.children())
|
||||||
|
return itertools.chain(files, dirs)
|
||||||
|
|
||||||
|
def open(self, *args, **kwargs):
|
||||||
|
raise IsADirectoryError()
|
||||||
|
|
||||||
|
|
||||||
|
class ResourceHandle(Traversable):
|
||||||
|
"""
|
||||||
|
Handle to a named resource in a ResourceReader.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, parent: ResourceContainer, name: str):
|
||||||
|
self.parent = parent
|
||||||
|
self.name = name # type: ignore
|
||||||
|
|
||||||
|
def is_file(self):
|
||||||
|
return True
|
||||||
|
|
||||||
|
def is_dir(self):
|
||||||
|
return False
|
||||||
|
|
||||||
|
def open(self, mode='r', *args, **kwargs):
|
||||||
|
stream = self.parent.reader.open_binary(self.name)
|
||||||
|
if 'b' not in mode:
|
||||||
|
stream = io.TextIOWrapper(*args, **kwargs)
|
||||||
|
return stream
|
||||||
|
|
||||||
|
def joinpath(self, name):
|
||||||
|
raise RuntimeError("Cannot traverse into a resource")
|
||||||
|
|
||||||
|
|
||||||
|
class TraversableReader(TraversableResources, SimpleReader):
|
||||||
|
"""
|
||||||
|
A TraversableResources based on SimpleReader. Resource providers
|
||||||
|
may derive from this class to provide the TraversableResources
|
||||||
|
interface by supplying the SimpleReader interface.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def files(self):
|
||||||
|
return ResourceContainer(self)
|
||||||
Binary file not shown.
Binary file not shown.
|
|
@ -0,0 +1,361 @@
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import contextlib
|
||||||
|
import functools
|
||||||
|
import operator
|
||||||
|
import os
|
||||||
|
import shutil
|
||||||
|
import subprocess
|
||||||
|
import sys
|
||||||
|
import tempfile
|
||||||
|
import urllib.request
|
||||||
|
import warnings
|
||||||
|
from typing import Iterator
|
||||||
|
|
||||||
|
|
||||||
|
if sys.version_info < (3, 12):
|
||||||
|
from pkg_resources.extern.backports import tarfile
|
||||||
|
else:
|
||||||
|
import tarfile
|
||||||
|
|
||||||
|
|
||||||
|
@contextlib.contextmanager
|
||||||
|
def pushd(dir: str | os.PathLike) -> Iterator[str | os.PathLike]:
|
||||||
|
"""
|
||||||
|
>>> tmp_path = getfixture('tmp_path')
|
||||||
|
>>> with pushd(tmp_path):
|
||||||
|
... assert os.getcwd() == os.fspath(tmp_path)
|
||||||
|
>>> assert os.getcwd() != os.fspath(tmp_path)
|
||||||
|
"""
|
||||||
|
|
||||||
|
orig = os.getcwd()
|
||||||
|
os.chdir(dir)
|
||||||
|
try:
|
||||||
|
yield dir
|
||||||
|
finally:
|
||||||
|
os.chdir(orig)
|
||||||
|
|
||||||
|
|
||||||
|
@contextlib.contextmanager
|
||||||
|
def tarball(
|
||||||
|
url, target_dir: str | os.PathLike | None = None
|
||||||
|
) -> Iterator[str | os.PathLike]:
|
||||||
|
"""
|
||||||
|
Get a tarball, extract it, yield, then clean up.
|
||||||
|
|
||||||
|
>>> import urllib.request
|
||||||
|
>>> url = getfixture('tarfile_served')
|
||||||
|
>>> target = getfixture('tmp_path') / 'out'
|
||||||
|
>>> tb = tarball(url, target_dir=target)
|
||||||
|
>>> import pathlib
|
||||||
|
>>> with tb as extracted:
|
||||||
|
... contents = pathlib.Path(extracted, 'contents.txt').read_text(encoding='utf-8')
|
||||||
|
>>> assert not os.path.exists(extracted)
|
||||||
|
"""
|
||||||
|
if target_dir is None:
|
||||||
|
target_dir = os.path.basename(url).replace('.tar.gz', '').replace('.tgz', '')
|
||||||
|
# In the tar command, use --strip-components=1 to strip the first path and
|
||||||
|
# then
|
||||||
|
# use -C to cause the files to be extracted to {target_dir}. This ensures
|
||||||
|
# that we always know where the files were extracted.
|
||||||
|
os.mkdir(target_dir)
|
||||||
|
try:
|
||||||
|
req = urllib.request.urlopen(url)
|
||||||
|
with tarfile.open(fileobj=req, mode='r|*') as tf:
|
||||||
|
tf.extractall(path=target_dir, filter=strip_first_component)
|
||||||
|
yield target_dir
|
||||||
|
finally:
|
||||||
|
shutil.rmtree(target_dir)
|
||||||
|
|
||||||
|
|
||||||
|
def strip_first_component(
|
||||||
|
member: tarfile.TarInfo,
|
||||||
|
path,
|
||||||
|
) -> tarfile.TarInfo:
|
||||||
|
_, member.name = member.name.split('/', 1)
|
||||||
|
return member
|
||||||
|
|
||||||
|
|
||||||
|
def _compose(*cmgrs):
|
||||||
|
"""
|
||||||
|
Compose any number of dependent context managers into a single one.
|
||||||
|
|
||||||
|
The last, innermost context manager may take arbitrary arguments, but
|
||||||
|
each successive context manager should accept the result from the
|
||||||
|
previous as a single parameter.
|
||||||
|
|
||||||
|
Like :func:`jaraco.functools.compose`, behavior works from right to
|
||||||
|
left, so the context manager should be indicated from outermost to
|
||||||
|
innermost.
|
||||||
|
|
||||||
|
Example, to create a context manager to change to a temporary
|
||||||
|
directory:
|
||||||
|
|
||||||
|
>>> temp_dir_as_cwd = _compose(pushd, temp_dir)
|
||||||
|
>>> with temp_dir_as_cwd() as dir:
|
||||||
|
... assert os.path.samefile(os.getcwd(), dir)
|
||||||
|
"""
|
||||||
|
|
||||||
|
def compose_two(inner, outer):
|
||||||
|
def composed(*args, **kwargs):
|
||||||
|
with inner(*args, **kwargs) as saved, outer(saved) as res:
|
||||||
|
yield res
|
||||||
|
|
||||||
|
return contextlib.contextmanager(composed)
|
||||||
|
|
||||||
|
return functools.reduce(compose_two, reversed(cmgrs))
|
||||||
|
|
||||||
|
|
||||||
|
tarball_cwd = _compose(pushd, tarball)
|
||||||
|
|
||||||
|
|
||||||
|
@contextlib.contextmanager
|
||||||
|
def tarball_context(*args, **kwargs):
|
||||||
|
warnings.warn(
|
||||||
|
"tarball_context is deprecated. Use tarball or tarball_cwd instead.",
|
||||||
|
DeprecationWarning,
|
||||||
|
stacklevel=2,
|
||||||
|
)
|
||||||
|
pushd_ctx = kwargs.pop('pushd', pushd)
|
||||||
|
with tarball(*args, **kwargs) as tball, pushd_ctx(tball) as dir:
|
||||||
|
yield dir
|
||||||
|
|
||||||
|
|
||||||
|
def infer_compression(url):
|
||||||
|
"""
|
||||||
|
Given a URL or filename, infer the compression code for tar.
|
||||||
|
|
||||||
|
>>> infer_compression('http://foo/bar.tar.gz')
|
||||||
|
'z'
|
||||||
|
>>> infer_compression('http://foo/bar.tgz')
|
||||||
|
'z'
|
||||||
|
>>> infer_compression('file.bz')
|
||||||
|
'j'
|
||||||
|
>>> infer_compression('file.xz')
|
||||||
|
'J'
|
||||||
|
"""
|
||||||
|
warnings.warn(
|
||||||
|
"infer_compression is deprecated with no replacement",
|
||||||
|
DeprecationWarning,
|
||||||
|
stacklevel=2,
|
||||||
|
)
|
||||||
|
# cheat and just assume it's the last two characters
|
||||||
|
compression_indicator = url[-2:]
|
||||||
|
mapping = dict(gz='z', bz='j', xz='J')
|
||||||
|
# Assume 'z' (gzip) if no match
|
||||||
|
return mapping.get(compression_indicator, 'z')
|
||||||
|
|
||||||
|
|
||||||
|
@contextlib.contextmanager
|
||||||
|
def temp_dir(remover=shutil.rmtree):
|
||||||
|
"""
|
||||||
|
Create a temporary directory context. Pass a custom remover
|
||||||
|
to override the removal behavior.
|
||||||
|
|
||||||
|
>>> import pathlib
|
||||||
|
>>> with temp_dir() as the_dir:
|
||||||
|
... assert os.path.isdir(the_dir)
|
||||||
|
... _ = pathlib.Path(the_dir).joinpath('somefile').write_text('contents', encoding='utf-8')
|
||||||
|
>>> assert not os.path.exists(the_dir)
|
||||||
|
"""
|
||||||
|
temp_dir = tempfile.mkdtemp()
|
||||||
|
try:
|
||||||
|
yield temp_dir
|
||||||
|
finally:
|
||||||
|
remover(temp_dir)
|
||||||
|
|
||||||
|
|
||||||
|
@contextlib.contextmanager
|
||||||
|
def repo_context(url, branch=None, quiet=True, dest_ctx=temp_dir):
|
||||||
|
"""
|
||||||
|
Check out the repo indicated by url.
|
||||||
|
|
||||||
|
If dest_ctx is supplied, it should be a context manager
|
||||||
|
to yield the target directory for the check out.
|
||||||
|
"""
|
||||||
|
exe = 'git' if 'git' in url else 'hg'
|
||||||
|
with dest_ctx() as repo_dir:
|
||||||
|
cmd = [exe, 'clone', url, repo_dir]
|
||||||
|
if branch:
|
||||||
|
cmd.extend(['--branch', branch])
|
||||||
|
devnull = open(os.path.devnull, 'w')
|
||||||
|
stdout = devnull if quiet else None
|
||||||
|
subprocess.check_call(cmd, stdout=stdout)
|
||||||
|
yield repo_dir
|
||||||
|
|
||||||
|
|
||||||
|
def null():
|
||||||
|
"""
|
||||||
|
A null context suitable to stand in for a meaningful context.
|
||||||
|
|
||||||
|
>>> with null() as value:
|
||||||
|
... assert value is None
|
||||||
|
|
||||||
|
This context is most useful when dealing with two or more code
|
||||||
|
branches but only some need a context. Wrap the others in a null
|
||||||
|
context to provide symmetry across all options.
|
||||||
|
"""
|
||||||
|
warnings.warn(
|
||||||
|
"null is deprecated. Use contextlib.nullcontext",
|
||||||
|
DeprecationWarning,
|
||||||
|
stacklevel=2,
|
||||||
|
)
|
||||||
|
return contextlib.nullcontext()
|
||||||
|
|
||||||
|
|
||||||
|
class ExceptionTrap:
|
||||||
|
"""
|
||||||
|
A context manager that will catch certain exceptions and provide an
|
||||||
|
indication they occurred.
|
||||||
|
|
||||||
|
>>> with ExceptionTrap() as trap:
|
||||||
|
... raise Exception()
|
||||||
|
>>> bool(trap)
|
||||||
|
True
|
||||||
|
|
||||||
|
>>> with ExceptionTrap() as trap:
|
||||||
|
... pass
|
||||||
|
>>> bool(trap)
|
||||||
|
False
|
||||||
|
|
||||||
|
>>> with ExceptionTrap(ValueError) as trap:
|
||||||
|
... raise ValueError("1 + 1 is not 3")
|
||||||
|
>>> bool(trap)
|
||||||
|
True
|
||||||
|
>>> trap.value
|
||||||
|
ValueError('1 + 1 is not 3')
|
||||||
|
>>> trap.tb
|
||||||
|
<traceback object at ...>
|
||||||
|
|
||||||
|
>>> with ExceptionTrap(ValueError) as trap:
|
||||||
|
... raise Exception()
|
||||||
|
Traceback (most recent call last):
|
||||||
|
...
|
||||||
|
Exception
|
||||||
|
|
||||||
|
>>> bool(trap)
|
||||||
|
False
|
||||||
|
"""
|
||||||
|
|
||||||
|
exc_info = None, None, None
|
||||||
|
|
||||||
|
def __init__(self, exceptions=(Exception,)):
|
||||||
|
self.exceptions = exceptions
|
||||||
|
|
||||||
|
def __enter__(self):
|
||||||
|
return self
|
||||||
|
|
||||||
|
@property
|
||||||
|
def type(self):
|
||||||
|
return self.exc_info[0]
|
||||||
|
|
||||||
|
@property
|
||||||
|
def value(self):
|
||||||
|
return self.exc_info[1]
|
||||||
|
|
||||||
|
@property
|
||||||
|
def tb(self):
|
||||||
|
return self.exc_info[2]
|
||||||
|
|
||||||
|
def __exit__(self, *exc_info):
|
||||||
|
type = exc_info[0]
|
||||||
|
matches = type and issubclass(type, self.exceptions)
|
||||||
|
if matches:
|
||||||
|
self.exc_info = exc_info
|
||||||
|
return matches
|
||||||
|
|
||||||
|
def __bool__(self):
|
||||||
|
return bool(self.type)
|
||||||
|
|
||||||
|
def raises(self, func, *, _test=bool):
|
||||||
|
"""
|
||||||
|
Wrap func and replace the result with the truth
|
||||||
|
value of the trap (True if an exception occurred).
|
||||||
|
|
||||||
|
First, give the decorator an alias to support Python 3.8
|
||||||
|
Syntax.
|
||||||
|
|
||||||
|
>>> raises = ExceptionTrap(ValueError).raises
|
||||||
|
|
||||||
|
Now decorate a function that always fails.
|
||||||
|
|
||||||
|
>>> @raises
|
||||||
|
... def fail():
|
||||||
|
... raise ValueError('failed')
|
||||||
|
>>> fail()
|
||||||
|
True
|
||||||
|
"""
|
||||||
|
|
||||||
|
@functools.wraps(func)
|
||||||
|
def wrapper(*args, **kwargs):
|
||||||
|
with ExceptionTrap(self.exceptions) as trap:
|
||||||
|
func(*args, **kwargs)
|
||||||
|
return _test(trap)
|
||||||
|
|
||||||
|
return wrapper
|
||||||
|
|
||||||
|
def passes(self, func):
|
||||||
|
"""
|
||||||
|
Wrap func and replace the result with the truth
|
||||||
|
value of the trap (True if no exception).
|
||||||
|
|
||||||
|
First, give the decorator an alias to support Python 3.8
|
||||||
|
Syntax.
|
||||||
|
|
||||||
|
>>> passes = ExceptionTrap(ValueError).passes
|
||||||
|
|
||||||
|
Now decorate a function that always fails.
|
||||||
|
|
||||||
|
>>> @passes
|
||||||
|
... def fail():
|
||||||
|
... raise ValueError('failed')
|
||||||
|
|
||||||
|
>>> fail()
|
||||||
|
False
|
||||||
|
"""
|
||||||
|
return self.raises(func, _test=operator.not_)
|
||||||
|
|
||||||
|
|
||||||
|
class suppress(contextlib.suppress, contextlib.ContextDecorator):
|
||||||
|
"""
|
||||||
|
A version of contextlib.suppress with decorator support.
|
||||||
|
|
||||||
|
>>> @suppress(KeyError)
|
||||||
|
... def key_error():
|
||||||
|
... {}['']
|
||||||
|
>>> key_error()
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class on_interrupt(contextlib.ContextDecorator):
|
||||||
|
"""
|
||||||
|
Replace a KeyboardInterrupt with SystemExit(1)
|
||||||
|
|
||||||
|
>>> def do_interrupt():
|
||||||
|
... raise KeyboardInterrupt()
|
||||||
|
>>> on_interrupt('error')(do_interrupt)()
|
||||||
|
Traceback (most recent call last):
|
||||||
|
...
|
||||||
|
SystemExit: 1
|
||||||
|
>>> on_interrupt('error', code=255)(do_interrupt)()
|
||||||
|
Traceback (most recent call last):
|
||||||
|
...
|
||||||
|
SystemExit: 255
|
||||||
|
>>> on_interrupt('suppress')(do_interrupt)()
|
||||||
|
>>> with __import__('pytest').raises(KeyboardInterrupt):
|
||||||
|
... on_interrupt('ignore')(do_interrupt)()
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, action='error', /, code=1):
|
||||||
|
self.action = action
|
||||||
|
self.code = code
|
||||||
|
|
||||||
|
def __enter__(self):
|
||||||
|
return self
|
||||||
|
|
||||||
|
def __exit__(self, exctype, excinst, exctb):
|
||||||
|
if exctype is not KeyboardInterrupt or self.action == 'ignore':
|
||||||
|
return
|
||||||
|
elif self.action == 'error':
|
||||||
|
raise SystemExit(self.code) from excinst
|
||||||
|
return self.action == 'suppress'
|
||||||
|
|
@ -0,0 +1,633 @@
|
||||||
|
import collections.abc
|
||||||
|
import functools
|
||||||
|
import inspect
|
||||||
|
import itertools
|
||||||
|
import operator
|
||||||
|
import time
|
||||||
|
import types
|
||||||
|
import warnings
|
||||||
|
|
||||||
|
import pkg_resources.extern.more_itertools
|
||||||
|
|
||||||
|
|
||||||
|
def compose(*funcs):
|
||||||
|
"""
|
||||||
|
Compose any number of unary functions into a single unary function.
|
||||||
|
|
||||||
|
>>> import textwrap
|
||||||
|
>>> expected = str.strip(textwrap.dedent(compose.__doc__))
|
||||||
|
>>> strip_and_dedent = compose(str.strip, textwrap.dedent)
|
||||||
|
>>> strip_and_dedent(compose.__doc__) == expected
|
||||||
|
True
|
||||||
|
|
||||||
|
Compose also allows the innermost function to take arbitrary arguments.
|
||||||
|
|
||||||
|
>>> round_three = lambda x: round(x, ndigits=3)
|
||||||
|
>>> f = compose(round_three, int.__truediv__)
|
||||||
|
>>> [f(3*x, x+1) for x in range(1,10)]
|
||||||
|
[1.5, 2.0, 2.25, 2.4, 2.5, 2.571, 2.625, 2.667, 2.7]
|
||||||
|
"""
|
||||||
|
|
||||||
|
def compose_two(f1, f2):
|
||||||
|
return lambda *args, **kwargs: f1(f2(*args, **kwargs))
|
||||||
|
|
||||||
|
return functools.reduce(compose_two, funcs)
|
||||||
|
|
||||||
|
|
||||||
|
def once(func):
|
||||||
|
"""
|
||||||
|
Decorate func so it's only ever called the first time.
|
||||||
|
|
||||||
|
This decorator can ensure that an expensive or non-idempotent function
|
||||||
|
will not be expensive on subsequent calls and is idempotent.
|
||||||
|
|
||||||
|
>>> add_three = once(lambda a: a+3)
|
||||||
|
>>> add_three(3)
|
||||||
|
6
|
||||||
|
>>> add_three(9)
|
||||||
|
6
|
||||||
|
>>> add_three('12')
|
||||||
|
6
|
||||||
|
|
||||||
|
To reset the stored value, simply clear the property ``saved_result``.
|
||||||
|
|
||||||
|
>>> del add_three.saved_result
|
||||||
|
>>> add_three(9)
|
||||||
|
12
|
||||||
|
>>> add_three(8)
|
||||||
|
12
|
||||||
|
|
||||||
|
Or invoke 'reset()' on it.
|
||||||
|
|
||||||
|
>>> add_three.reset()
|
||||||
|
>>> add_three(-3)
|
||||||
|
0
|
||||||
|
>>> add_three(0)
|
||||||
|
0
|
||||||
|
"""
|
||||||
|
|
||||||
|
@functools.wraps(func)
|
||||||
|
def wrapper(*args, **kwargs):
|
||||||
|
if not hasattr(wrapper, 'saved_result'):
|
||||||
|
wrapper.saved_result = func(*args, **kwargs)
|
||||||
|
return wrapper.saved_result
|
||||||
|
|
||||||
|
wrapper.reset = lambda: vars(wrapper).__delitem__('saved_result')
|
||||||
|
return wrapper
|
||||||
|
|
||||||
|
|
||||||
|
def method_cache(method, cache_wrapper=functools.lru_cache()):
|
||||||
|
"""
|
||||||
|
Wrap lru_cache to support storing the cache data in the object instances.
|
||||||
|
|
||||||
|
Abstracts the common paradigm where the method explicitly saves an
|
||||||
|
underscore-prefixed protected property on first call and returns that
|
||||||
|
subsequently.
|
||||||
|
|
||||||
|
>>> class MyClass:
|
||||||
|
... calls = 0
|
||||||
|
...
|
||||||
|
... @method_cache
|
||||||
|
... def method(self, value):
|
||||||
|
... self.calls += 1
|
||||||
|
... return value
|
||||||
|
|
||||||
|
>>> a = MyClass()
|
||||||
|
>>> a.method(3)
|
||||||
|
3
|
||||||
|
>>> for x in range(75):
|
||||||
|
... res = a.method(x)
|
||||||
|
>>> a.calls
|
||||||
|
75
|
||||||
|
|
||||||
|
Note that the apparent behavior will be exactly like that of lru_cache
|
||||||
|
except that the cache is stored on each instance, so values in one
|
||||||
|
instance will not flush values from another, and when an instance is
|
||||||
|
deleted, so are the cached values for that instance.
|
||||||
|
|
||||||
|
>>> b = MyClass()
|
||||||
|
>>> for x in range(35):
|
||||||
|
... res = b.method(x)
|
||||||
|
>>> b.calls
|
||||||
|
35
|
||||||
|
>>> a.method(0)
|
||||||
|
0
|
||||||
|
>>> a.calls
|
||||||
|
75
|
||||||
|
|
||||||
|
Note that if method had been decorated with ``functools.lru_cache()``,
|
||||||
|
a.calls would have been 76 (due to the cached value of 0 having been
|
||||||
|
flushed by the 'b' instance).
|
||||||
|
|
||||||
|
Clear the cache with ``.cache_clear()``
|
||||||
|
|
||||||
|
>>> a.method.cache_clear()
|
||||||
|
|
||||||
|
Same for a method that hasn't yet been called.
|
||||||
|
|
||||||
|
>>> c = MyClass()
|
||||||
|
>>> c.method.cache_clear()
|
||||||
|
|
||||||
|
Another cache wrapper may be supplied:
|
||||||
|
|
||||||
|
>>> cache = functools.lru_cache(maxsize=2)
|
||||||
|
>>> MyClass.method2 = method_cache(lambda self: 3, cache_wrapper=cache)
|
||||||
|
>>> a = MyClass()
|
||||||
|
>>> a.method2()
|
||||||
|
3
|
||||||
|
|
||||||
|
Caution - do not subsequently wrap the method with another decorator, such
|
||||||
|
as ``@property``, which changes the semantics of the function.
|
||||||
|
|
||||||
|
See also
|
||||||
|
http://code.activestate.com/recipes/577452-a-memoize-decorator-for-instance-methods/
|
||||||
|
for another implementation and additional justification.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def wrapper(self, *args, **kwargs):
|
||||||
|
# it's the first call, replace the method with a cached, bound method
|
||||||
|
bound_method = types.MethodType(method, self)
|
||||||
|
cached_method = cache_wrapper(bound_method)
|
||||||
|
setattr(self, method.__name__, cached_method)
|
||||||
|
return cached_method(*args, **kwargs)
|
||||||
|
|
||||||
|
# Support cache clear even before cache has been created.
|
||||||
|
wrapper.cache_clear = lambda: None
|
||||||
|
|
||||||
|
return _special_method_cache(method, cache_wrapper) or wrapper
|
||||||
|
|
||||||
|
|
||||||
|
def _special_method_cache(method, cache_wrapper):
|
||||||
|
"""
|
||||||
|
Because Python treats special methods differently, it's not
|
||||||
|
possible to use instance attributes to implement the cached
|
||||||
|
methods.
|
||||||
|
|
||||||
|
Instead, install the wrapper method under a different name
|
||||||
|
and return a simple proxy to that wrapper.
|
||||||
|
|
||||||
|
https://github.com/jaraco/jaraco.functools/issues/5
|
||||||
|
"""
|
||||||
|
name = method.__name__
|
||||||
|
special_names = '__getattr__', '__getitem__'
|
||||||
|
|
||||||
|
if name not in special_names:
|
||||||
|
return None
|
||||||
|
|
||||||
|
wrapper_name = '__cached' + name
|
||||||
|
|
||||||
|
def proxy(self, /, *args, **kwargs):
|
||||||
|
if wrapper_name not in vars(self):
|
||||||
|
bound = types.MethodType(method, self)
|
||||||
|
cache = cache_wrapper(bound)
|
||||||
|
setattr(self, wrapper_name, cache)
|
||||||
|
else:
|
||||||
|
cache = getattr(self, wrapper_name)
|
||||||
|
return cache(*args, **kwargs)
|
||||||
|
|
||||||
|
return proxy
|
||||||
|
|
||||||
|
|
||||||
|
def apply(transform):
|
||||||
|
"""
|
||||||
|
Decorate a function with a transform function that is
|
||||||
|
invoked on results returned from the decorated function.
|
||||||
|
|
||||||
|
>>> @apply(reversed)
|
||||||
|
... def get_numbers(start):
|
||||||
|
... "doc for get_numbers"
|
||||||
|
... return range(start, start+3)
|
||||||
|
>>> list(get_numbers(4))
|
||||||
|
[6, 5, 4]
|
||||||
|
>>> get_numbers.__doc__
|
||||||
|
'doc for get_numbers'
|
||||||
|
"""
|
||||||
|
|
||||||
|
def wrap(func):
|
||||||
|
return functools.wraps(func)(compose(transform, func))
|
||||||
|
|
||||||
|
return wrap
|
||||||
|
|
||||||
|
|
||||||
|
def result_invoke(action):
|
||||||
|
r"""
|
||||||
|
Decorate a function with an action function that is
|
||||||
|
invoked on the results returned from the decorated
|
||||||
|
function (for its side effect), then return the original
|
||||||
|
result.
|
||||||
|
|
||||||
|
>>> @result_invoke(print)
|
||||||
|
... def add_two(a, b):
|
||||||
|
... return a + b
|
||||||
|
>>> x = add_two(2, 3)
|
||||||
|
5
|
||||||
|
>>> x
|
||||||
|
5
|
||||||
|
"""
|
||||||
|
|
||||||
|
def wrap(func):
|
||||||
|
@functools.wraps(func)
|
||||||
|
def wrapper(*args, **kwargs):
|
||||||
|
result = func(*args, **kwargs)
|
||||||
|
action(result)
|
||||||
|
return result
|
||||||
|
|
||||||
|
return wrapper
|
||||||
|
|
||||||
|
return wrap
|
||||||
|
|
||||||
|
|
||||||
|
def invoke(f, /, *args, **kwargs):
|
||||||
|
"""
|
||||||
|
Call a function for its side effect after initialization.
|
||||||
|
|
||||||
|
The benefit of using the decorator instead of simply invoking a function
|
||||||
|
after defining it is that it makes explicit the author's intent for the
|
||||||
|
function to be called immediately. Whereas if one simply calls the
|
||||||
|
function immediately, it's less obvious if that was intentional or
|
||||||
|
incidental. It also avoids repeating the name - the two actions, defining
|
||||||
|
the function and calling it immediately are modeled separately, but linked
|
||||||
|
by the decorator construct.
|
||||||
|
|
||||||
|
The benefit of having a function construct (opposed to just invoking some
|
||||||
|
behavior inline) is to serve as a scope in which the behavior occurs. It
|
||||||
|
avoids polluting the global namespace with local variables, provides an
|
||||||
|
anchor on which to attach documentation (docstring), keeps the behavior
|
||||||
|
logically separated (instead of conceptually separated or not separated at
|
||||||
|
all), and provides potential to re-use the behavior for testing or other
|
||||||
|
purposes.
|
||||||
|
|
||||||
|
This function is named as a pithy way to communicate, "call this function
|
||||||
|
primarily for its side effect", or "while defining this function, also
|
||||||
|
take it aside and call it". It exists because there's no Python construct
|
||||||
|
for "define and call" (nor should there be, as decorators serve this need
|
||||||
|
just fine). The behavior happens immediately and synchronously.
|
||||||
|
|
||||||
|
>>> @invoke
|
||||||
|
... def func(): print("called")
|
||||||
|
called
|
||||||
|
>>> func()
|
||||||
|
called
|
||||||
|
|
||||||
|
Use functools.partial to pass parameters to the initial call
|
||||||
|
|
||||||
|
>>> @functools.partial(invoke, name='bingo')
|
||||||
|
... def func(name): print('called with', name)
|
||||||
|
called with bingo
|
||||||
|
"""
|
||||||
|
f(*args, **kwargs)
|
||||||
|
return f
|
||||||
|
|
||||||
|
|
||||||
|
class Throttler:
|
||||||
|
"""Rate-limit a function (or other callable)."""
|
||||||
|
|
||||||
|
def __init__(self, func, max_rate=float('Inf')):
|
||||||
|
if isinstance(func, Throttler):
|
||||||
|
func = func.func
|
||||||
|
self.func = func
|
||||||
|
self.max_rate = max_rate
|
||||||
|
self.reset()
|
||||||
|
|
||||||
|
def reset(self):
|
||||||
|
self.last_called = 0
|
||||||
|
|
||||||
|
def __call__(self, *args, **kwargs):
|
||||||
|
self._wait()
|
||||||
|
return self.func(*args, **kwargs)
|
||||||
|
|
||||||
|
def _wait(self):
|
||||||
|
"""Ensure at least 1/max_rate seconds from last call."""
|
||||||
|
elapsed = time.time() - self.last_called
|
||||||
|
must_wait = 1 / self.max_rate - elapsed
|
||||||
|
time.sleep(max(0, must_wait))
|
||||||
|
self.last_called = time.time()
|
||||||
|
|
||||||
|
def __get__(self, obj, owner=None):
|
||||||
|
return first_invoke(self._wait, functools.partial(self.func, obj))
|
||||||
|
|
||||||
|
|
||||||
|
def first_invoke(func1, func2):
|
||||||
|
"""
|
||||||
|
Return a function that when invoked will invoke func1 without
|
||||||
|
any parameters (for its side effect) and then invoke func2
|
||||||
|
with whatever parameters were passed, returning its result.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def wrapper(*args, **kwargs):
|
||||||
|
func1()
|
||||||
|
return func2(*args, **kwargs)
|
||||||
|
|
||||||
|
return wrapper
|
||||||
|
|
||||||
|
|
||||||
|
method_caller = first_invoke(
|
||||||
|
lambda: warnings.warn(
|
||||||
|
'`jaraco.functools.method_caller` is deprecated, '
|
||||||
|
'use `operator.methodcaller` instead',
|
||||||
|
DeprecationWarning,
|
||||||
|
stacklevel=3,
|
||||||
|
),
|
||||||
|
operator.methodcaller,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def retry_call(func, cleanup=lambda: None, retries=0, trap=()):
|
||||||
|
"""
|
||||||
|
Given a callable func, trap the indicated exceptions
|
||||||
|
for up to 'retries' times, invoking cleanup on the
|
||||||
|
exception. On the final attempt, allow any exceptions
|
||||||
|
to propagate.
|
||||||
|
"""
|
||||||
|
attempts = itertools.count() if retries == float('inf') else range(retries)
|
||||||
|
for _ in attempts:
|
||||||
|
try:
|
||||||
|
return func()
|
||||||
|
except trap:
|
||||||
|
cleanup()
|
||||||
|
|
||||||
|
return func()
|
||||||
|
|
||||||
|
|
||||||
|
def retry(*r_args, **r_kwargs):
|
||||||
|
"""
|
||||||
|
Decorator wrapper for retry_call. Accepts arguments to retry_call
|
||||||
|
except func and then returns a decorator for the decorated function.
|
||||||
|
|
||||||
|
Ex:
|
||||||
|
|
||||||
|
>>> @retry(retries=3)
|
||||||
|
... def my_func(a, b):
|
||||||
|
... "this is my funk"
|
||||||
|
... print(a, b)
|
||||||
|
>>> my_func.__doc__
|
||||||
|
'this is my funk'
|
||||||
|
"""
|
||||||
|
|
||||||
|
def decorate(func):
|
||||||
|
@functools.wraps(func)
|
||||||
|
def wrapper(*f_args, **f_kwargs):
|
||||||
|
bound = functools.partial(func, *f_args, **f_kwargs)
|
||||||
|
return retry_call(bound, *r_args, **r_kwargs)
|
||||||
|
|
||||||
|
return wrapper
|
||||||
|
|
||||||
|
return decorate
|
||||||
|
|
||||||
|
|
||||||
|
def print_yielded(func):
|
||||||
|
"""
|
||||||
|
Convert a generator into a function that prints all yielded elements.
|
||||||
|
|
||||||
|
>>> @print_yielded
|
||||||
|
... def x():
|
||||||
|
... yield 3; yield None
|
||||||
|
>>> x()
|
||||||
|
3
|
||||||
|
None
|
||||||
|
"""
|
||||||
|
print_all = functools.partial(map, print)
|
||||||
|
print_results = compose(more_itertools.consume, print_all, func)
|
||||||
|
return functools.wraps(func)(print_results)
|
||||||
|
|
||||||
|
|
||||||
|
def pass_none(func):
|
||||||
|
"""
|
||||||
|
Wrap func so it's not called if its first param is None.
|
||||||
|
|
||||||
|
>>> print_text = pass_none(print)
|
||||||
|
>>> print_text('text')
|
||||||
|
text
|
||||||
|
>>> print_text(None)
|
||||||
|
"""
|
||||||
|
|
||||||
|
@functools.wraps(func)
|
||||||
|
def wrapper(param, /, *args, **kwargs):
|
||||||
|
if param is not None:
|
||||||
|
return func(param, *args, **kwargs)
|
||||||
|
return None
|
||||||
|
|
||||||
|
return wrapper
|
||||||
|
|
||||||
|
|
||||||
|
def assign_params(func, namespace):
|
||||||
|
"""
|
||||||
|
Assign parameters from namespace where func solicits.
|
||||||
|
|
||||||
|
>>> def func(x, y=3):
|
||||||
|
... print(x, y)
|
||||||
|
>>> assigned = assign_params(func, dict(x=2, z=4))
|
||||||
|
>>> assigned()
|
||||||
|
2 3
|
||||||
|
|
||||||
|
The usual errors are raised if a function doesn't receive
|
||||||
|
its required parameters:
|
||||||
|
|
||||||
|
>>> assigned = assign_params(func, dict(y=3, z=4))
|
||||||
|
>>> assigned()
|
||||||
|
Traceback (most recent call last):
|
||||||
|
TypeError: func() ...argument...
|
||||||
|
|
||||||
|
It even works on methods:
|
||||||
|
|
||||||
|
>>> class Handler:
|
||||||
|
... def meth(self, arg):
|
||||||
|
... print(arg)
|
||||||
|
>>> assign_params(Handler().meth, dict(arg='crystal', foo='clear'))()
|
||||||
|
crystal
|
||||||
|
"""
|
||||||
|
sig = inspect.signature(func)
|
||||||
|
params = sig.parameters.keys()
|
||||||
|
call_ns = {k: namespace[k] for k in params if k in namespace}
|
||||||
|
return functools.partial(func, **call_ns)
|
||||||
|
|
||||||
|
|
||||||
|
def save_method_args(method):
|
||||||
|
"""
|
||||||
|
Wrap a method such that when it is called, the args and kwargs are
|
||||||
|
saved on the method.
|
||||||
|
|
||||||
|
>>> class MyClass:
|
||||||
|
... @save_method_args
|
||||||
|
... def method(self, a, b):
|
||||||
|
... print(a, b)
|
||||||
|
>>> my_ob = MyClass()
|
||||||
|
>>> my_ob.method(1, 2)
|
||||||
|
1 2
|
||||||
|
>>> my_ob._saved_method.args
|
||||||
|
(1, 2)
|
||||||
|
>>> my_ob._saved_method.kwargs
|
||||||
|
{}
|
||||||
|
>>> my_ob.method(a=3, b='foo')
|
||||||
|
3 foo
|
||||||
|
>>> my_ob._saved_method.args
|
||||||
|
()
|
||||||
|
>>> my_ob._saved_method.kwargs == dict(a=3, b='foo')
|
||||||
|
True
|
||||||
|
|
||||||
|
The arguments are stored on the instance, allowing for
|
||||||
|
different instance to save different args.
|
||||||
|
|
||||||
|
>>> your_ob = MyClass()
|
||||||
|
>>> your_ob.method({str('x'): 3}, b=[4])
|
||||||
|
{'x': 3} [4]
|
||||||
|
>>> your_ob._saved_method.args
|
||||||
|
({'x': 3},)
|
||||||
|
>>> my_ob._saved_method.args
|
||||||
|
()
|
||||||
|
"""
|
||||||
|
args_and_kwargs = collections.namedtuple('args_and_kwargs', 'args kwargs')
|
||||||
|
|
||||||
|
@functools.wraps(method)
|
||||||
|
def wrapper(self, /, *args, **kwargs):
|
||||||
|
attr_name = '_saved_' + method.__name__
|
||||||
|
attr = args_and_kwargs(args, kwargs)
|
||||||
|
setattr(self, attr_name, attr)
|
||||||
|
return method(self, *args, **kwargs)
|
||||||
|
|
||||||
|
return wrapper
|
||||||
|
|
||||||
|
|
||||||
|
def except_(*exceptions, replace=None, use=None):
|
||||||
|
"""
|
||||||
|
Replace the indicated exceptions, if raised, with the indicated
|
||||||
|
literal replacement or evaluated expression (if present).
|
||||||
|
|
||||||
|
>>> safe_int = except_(ValueError)(int)
|
||||||
|
>>> safe_int('five')
|
||||||
|
>>> safe_int('5')
|
||||||
|
5
|
||||||
|
|
||||||
|
Specify a literal replacement with ``replace``.
|
||||||
|
|
||||||
|
>>> safe_int_r = except_(ValueError, replace=0)(int)
|
||||||
|
>>> safe_int_r('five')
|
||||||
|
0
|
||||||
|
|
||||||
|
Provide an expression to ``use`` to pass through particular parameters.
|
||||||
|
|
||||||
|
>>> safe_int_pt = except_(ValueError, use='args[0]')(int)
|
||||||
|
>>> safe_int_pt('five')
|
||||||
|
'five'
|
||||||
|
|
||||||
|
"""
|
||||||
|
|
||||||
|
def decorate(func):
|
||||||
|
@functools.wraps(func)
|
||||||
|
def wrapper(*args, **kwargs):
|
||||||
|
try:
|
||||||
|
return func(*args, **kwargs)
|
||||||
|
except exceptions:
|
||||||
|
try:
|
||||||
|
return eval(use)
|
||||||
|
except TypeError:
|
||||||
|
return replace
|
||||||
|
|
||||||
|
return wrapper
|
||||||
|
|
||||||
|
return decorate
|
||||||
|
|
||||||
|
|
||||||
|
def identity(x):
|
||||||
|
"""
|
||||||
|
Return the argument.
|
||||||
|
|
||||||
|
>>> o = object()
|
||||||
|
>>> identity(o) is o
|
||||||
|
True
|
||||||
|
"""
|
||||||
|
return x
|
||||||
|
|
||||||
|
|
||||||
|
def bypass_when(check, *, _op=identity):
|
||||||
|
"""
|
||||||
|
Decorate a function to return its parameter when ``check``.
|
||||||
|
|
||||||
|
>>> bypassed = [] # False
|
||||||
|
|
||||||
|
>>> @bypass_when(bypassed)
|
||||||
|
... def double(x):
|
||||||
|
... return x * 2
|
||||||
|
>>> double(2)
|
||||||
|
4
|
||||||
|
>>> bypassed[:] = [object()] # True
|
||||||
|
>>> double(2)
|
||||||
|
2
|
||||||
|
"""
|
||||||
|
|
||||||
|
def decorate(func):
|
||||||
|
@functools.wraps(func)
|
||||||
|
def wrapper(param, /):
|
||||||
|
return param if _op(check) else func(param)
|
||||||
|
|
||||||
|
return wrapper
|
||||||
|
|
||||||
|
return decorate
|
||||||
|
|
||||||
|
|
||||||
|
def bypass_unless(check):
|
||||||
|
"""
|
||||||
|
Decorate a function to return its parameter unless ``check``.
|
||||||
|
|
||||||
|
>>> enabled = [object()] # True
|
||||||
|
|
||||||
|
>>> @bypass_unless(enabled)
|
||||||
|
... def double(x):
|
||||||
|
... return x * 2
|
||||||
|
>>> double(2)
|
||||||
|
4
|
||||||
|
>>> del enabled[:] # False
|
||||||
|
>>> double(2)
|
||||||
|
2
|
||||||
|
"""
|
||||||
|
return bypass_when(check, _op=operator.not_)
|
||||||
|
|
||||||
|
|
||||||
|
@functools.singledispatch
|
||||||
|
def _splat_inner(args, func):
|
||||||
|
"""Splat args to func."""
|
||||||
|
return func(*args)
|
||||||
|
|
||||||
|
|
||||||
|
@_splat_inner.register
|
||||||
|
def _(args: collections.abc.Mapping, func):
|
||||||
|
"""Splat kargs to func as kwargs."""
|
||||||
|
return func(**args)
|
||||||
|
|
||||||
|
|
||||||
|
def splat(func):
|
||||||
|
"""
|
||||||
|
Wrap func to expect its parameters to be passed positionally in a tuple.
|
||||||
|
|
||||||
|
Has a similar effect to that of ``itertools.starmap`` over
|
||||||
|
simple ``map``.
|
||||||
|
|
||||||
|
>>> pairs = [(-1, 1), (0, 2)]
|
||||||
|
>>> pkg_resources.extern.more_itertools.consume(itertools.starmap(print, pairs))
|
||||||
|
-1 1
|
||||||
|
0 2
|
||||||
|
>>> pkg_resources.extern.more_itertools.consume(map(splat(print), pairs))
|
||||||
|
-1 1
|
||||||
|
0 2
|
||||||
|
|
||||||
|
The approach generalizes to other iterators that don't have a "star"
|
||||||
|
equivalent, such as a "starfilter".
|
||||||
|
|
||||||
|
>>> list(filter(splat(operator.add), pairs))
|
||||||
|
[(0, 2)]
|
||||||
|
|
||||||
|
Splat also accepts a mapping argument.
|
||||||
|
|
||||||
|
>>> def is_nice(msg, code):
|
||||||
|
... return "smile" in msg or code == 0
|
||||||
|
>>> msgs = [
|
||||||
|
... dict(msg='smile!', code=20),
|
||||||
|
... dict(msg='error :(', code=1),
|
||||||
|
... dict(msg='unknown', code=0),
|
||||||
|
... ]
|
||||||
|
>>> for msg in filter(splat(is_nice), msgs):
|
||||||
|
... print(msg)
|
||||||
|
{'msg': 'smile!', 'code': 20}
|
||||||
|
{'msg': 'unknown', 'code': 0}
|
||||||
|
"""
|
||||||
|
return functools.wraps(func)(functools.partial(_splat_inner, func=func))
|
||||||
|
|
@ -0,0 +1,128 @@
|
||||||
|
from collections.abc import Callable, Hashable, Iterator
|
||||||
|
from functools import partial
|
||||||
|
from operator import methodcaller
|
||||||
|
import sys
|
||||||
|
from typing import (
|
||||||
|
Any,
|
||||||
|
Generic,
|
||||||
|
Protocol,
|
||||||
|
TypeVar,
|
||||||
|
overload,
|
||||||
|
)
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 10):
|
||||||
|
from typing import Concatenate, ParamSpec
|
||||||
|
else:
|
||||||
|
from typing_extensions import Concatenate, ParamSpec
|
||||||
|
|
||||||
|
_P = ParamSpec('_P')
|
||||||
|
_R = TypeVar('_R')
|
||||||
|
_T = TypeVar('_T')
|
||||||
|
_R1 = TypeVar('_R1')
|
||||||
|
_R2 = TypeVar('_R2')
|
||||||
|
_V = TypeVar('_V')
|
||||||
|
_S = TypeVar('_S')
|
||||||
|
_R_co = TypeVar('_R_co', covariant=True)
|
||||||
|
|
||||||
|
class _OnceCallable(Protocol[_P, _R]):
|
||||||
|
saved_result: _R
|
||||||
|
reset: Callable[[], None]
|
||||||
|
def __call__(self, *args: _P.args, **kwargs: _P.kwargs) -> _R: ...
|
||||||
|
|
||||||
|
class _ProxyMethodCacheWrapper(Protocol[_R_co]):
|
||||||
|
cache_clear: Callable[[], None]
|
||||||
|
def __call__(self, *args: Hashable, **kwargs: Hashable) -> _R_co: ...
|
||||||
|
|
||||||
|
class _MethodCacheWrapper(Protocol[_R_co]):
|
||||||
|
def cache_clear(self) -> None: ...
|
||||||
|
def __call__(self, *args: Hashable, **kwargs: Hashable) -> _R_co: ...
|
||||||
|
|
||||||
|
# `compose()` overloads below will cover most use cases.
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def compose(
|
||||||
|
__func1: Callable[[_R], _T],
|
||||||
|
__func2: Callable[_P, _R],
|
||||||
|
/,
|
||||||
|
) -> Callable[_P, _T]: ...
|
||||||
|
@overload
|
||||||
|
def compose(
|
||||||
|
__func1: Callable[[_R], _T],
|
||||||
|
__func2: Callable[[_R1], _R],
|
||||||
|
__func3: Callable[_P, _R1],
|
||||||
|
/,
|
||||||
|
) -> Callable[_P, _T]: ...
|
||||||
|
@overload
|
||||||
|
def compose(
|
||||||
|
__func1: Callable[[_R], _T],
|
||||||
|
__func2: Callable[[_R2], _R],
|
||||||
|
__func3: Callable[[_R1], _R2],
|
||||||
|
__func4: Callable[_P, _R1],
|
||||||
|
/,
|
||||||
|
) -> Callable[_P, _T]: ...
|
||||||
|
def once(func: Callable[_P, _R]) -> _OnceCallable[_P, _R]: ...
|
||||||
|
def method_cache(
|
||||||
|
method: Callable[..., _R],
|
||||||
|
cache_wrapper: Callable[[Callable[..., _R]], _MethodCacheWrapper[_R]] = ...,
|
||||||
|
) -> _MethodCacheWrapper[_R] | _ProxyMethodCacheWrapper[_R]: ...
|
||||||
|
def apply(
|
||||||
|
transform: Callable[[_R], _T]
|
||||||
|
) -> Callable[[Callable[_P, _R]], Callable[_P, _T]]: ...
|
||||||
|
def result_invoke(
|
||||||
|
action: Callable[[_R], Any]
|
||||||
|
) -> Callable[[Callable[_P, _R]], Callable[_P, _R]]: ...
|
||||||
|
def invoke(
|
||||||
|
f: Callable[_P, _R], /, *args: _P.args, **kwargs: _P.kwargs
|
||||||
|
) -> Callable[_P, _R]: ...
|
||||||
|
def call_aside(
|
||||||
|
f: Callable[_P, _R], *args: _P.args, **kwargs: _P.kwargs
|
||||||
|
) -> Callable[_P, _R]: ...
|
||||||
|
|
||||||
|
class Throttler(Generic[_R]):
|
||||||
|
last_called: float
|
||||||
|
func: Callable[..., _R]
|
||||||
|
max_rate: float
|
||||||
|
def __init__(
|
||||||
|
self, func: Callable[..., _R] | Throttler[_R], max_rate: float = ...
|
||||||
|
) -> None: ...
|
||||||
|
def reset(self) -> None: ...
|
||||||
|
def __call__(self, *args: Any, **kwargs: Any) -> _R: ...
|
||||||
|
def __get__(self, obj: Any, owner: type[Any] | None = ...) -> Callable[..., _R]: ...
|
||||||
|
|
||||||
|
def first_invoke(
|
||||||
|
func1: Callable[..., Any], func2: Callable[_P, _R]
|
||||||
|
) -> Callable[_P, _R]: ...
|
||||||
|
|
||||||
|
method_caller: Callable[..., methodcaller]
|
||||||
|
|
||||||
|
def retry_call(
|
||||||
|
func: Callable[..., _R],
|
||||||
|
cleanup: Callable[..., None] = ...,
|
||||||
|
retries: int | float = ...,
|
||||||
|
trap: type[BaseException] | tuple[type[BaseException], ...] = ...,
|
||||||
|
) -> _R: ...
|
||||||
|
def retry(
|
||||||
|
cleanup: Callable[..., None] = ...,
|
||||||
|
retries: int | float = ...,
|
||||||
|
trap: type[BaseException] | tuple[type[BaseException], ...] = ...,
|
||||||
|
) -> Callable[[Callable[..., _R]], Callable[..., _R]]: ...
|
||||||
|
def print_yielded(func: Callable[_P, Iterator[Any]]) -> Callable[_P, None]: ...
|
||||||
|
def pass_none(
|
||||||
|
func: Callable[Concatenate[_T, _P], _R]
|
||||||
|
) -> Callable[Concatenate[_T, _P], _R]: ...
|
||||||
|
def assign_params(
|
||||||
|
func: Callable[..., _R], namespace: dict[str, Any]
|
||||||
|
) -> partial[_R]: ...
|
||||||
|
def save_method_args(
|
||||||
|
method: Callable[Concatenate[_S, _P], _R]
|
||||||
|
) -> Callable[Concatenate[_S, _P], _R]: ...
|
||||||
|
def except_(
|
||||||
|
*exceptions: type[BaseException], replace: Any = ..., use: Any = ...
|
||||||
|
) -> Callable[[Callable[_P, Any]], Callable[_P, Any]]: ...
|
||||||
|
def identity(x: _T) -> _T: ...
|
||||||
|
def bypass_when(
|
||||||
|
check: _V, *, _op: Callable[[_V], Any] = ...
|
||||||
|
) -> Callable[[Callable[[_T], _R]], Callable[[_T], _T | _R]]: ...
|
||||||
|
def bypass_unless(
|
||||||
|
check: Any,
|
||||||
|
) -> Callable[[Callable[[_T], _R]], Callable[[_T], _T | _R]]: ...
|
||||||
Binary file not shown.
|
|
@ -0,0 +1,599 @@
|
||||||
|
import re
|
||||||
|
import itertools
|
||||||
|
import textwrap
|
||||||
|
import functools
|
||||||
|
|
||||||
|
try:
|
||||||
|
from importlib.resources import files # type: ignore
|
||||||
|
except ImportError: # pragma: nocover
|
||||||
|
from pkg_resources.extern.importlib_resources import files # type: ignore
|
||||||
|
|
||||||
|
from pkg_resources.extern.jaraco.functools import compose, method_cache
|
||||||
|
from pkg_resources.extern.jaraco.context import ExceptionTrap
|
||||||
|
|
||||||
|
|
||||||
|
def substitution(old, new):
|
||||||
|
"""
|
||||||
|
Return a function that will perform a substitution on a string
|
||||||
|
"""
|
||||||
|
return lambda s: s.replace(old, new)
|
||||||
|
|
||||||
|
|
||||||
|
def multi_substitution(*substitutions):
|
||||||
|
"""
|
||||||
|
Take a sequence of pairs specifying substitutions, and create
|
||||||
|
a function that performs those substitutions.
|
||||||
|
|
||||||
|
>>> multi_substitution(('foo', 'bar'), ('bar', 'baz'))('foo')
|
||||||
|
'baz'
|
||||||
|
"""
|
||||||
|
substitutions = itertools.starmap(substitution, substitutions)
|
||||||
|
# compose function applies last function first, so reverse the
|
||||||
|
# substitutions to get the expected order.
|
||||||
|
substitutions = reversed(tuple(substitutions))
|
||||||
|
return compose(*substitutions)
|
||||||
|
|
||||||
|
|
||||||
|
class FoldedCase(str):
|
||||||
|
"""
|
||||||
|
A case insensitive string class; behaves just like str
|
||||||
|
except compares equal when the only variation is case.
|
||||||
|
|
||||||
|
>>> s = FoldedCase('hello world')
|
||||||
|
|
||||||
|
>>> s == 'Hello World'
|
||||||
|
True
|
||||||
|
|
||||||
|
>>> 'Hello World' == s
|
||||||
|
True
|
||||||
|
|
||||||
|
>>> s != 'Hello World'
|
||||||
|
False
|
||||||
|
|
||||||
|
>>> s.index('O')
|
||||||
|
4
|
||||||
|
|
||||||
|
>>> s.split('O')
|
||||||
|
['hell', ' w', 'rld']
|
||||||
|
|
||||||
|
>>> sorted(map(FoldedCase, ['GAMMA', 'alpha', 'Beta']))
|
||||||
|
['alpha', 'Beta', 'GAMMA']
|
||||||
|
|
||||||
|
Sequence membership is straightforward.
|
||||||
|
|
||||||
|
>>> "Hello World" in [s]
|
||||||
|
True
|
||||||
|
>>> s in ["Hello World"]
|
||||||
|
True
|
||||||
|
|
||||||
|
You may test for set inclusion, but candidate and elements
|
||||||
|
must both be folded.
|
||||||
|
|
||||||
|
>>> FoldedCase("Hello World") in {s}
|
||||||
|
True
|
||||||
|
>>> s in {FoldedCase("Hello World")}
|
||||||
|
True
|
||||||
|
|
||||||
|
String inclusion works as long as the FoldedCase object
|
||||||
|
is on the right.
|
||||||
|
|
||||||
|
>>> "hello" in FoldedCase("Hello World")
|
||||||
|
True
|
||||||
|
|
||||||
|
But not if the FoldedCase object is on the left:
|
||||||
|
|
||||||
|
>>> FoldedCase('hello') in 'Hello World'
|
||||||
|
False
|
||||||
|
|
||||||
|
In that case, use ``in_``:
|
||||||
|
|
||||||
|
>>> FoldedCase('hello').in_('Hello World')
|
||||||
|
True
|
||||||
|
|
||||||
|
>>> FoldedCase('hello') > FoldedCase('Hello')
|
||||||
|
False
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __lt__(self, other):
|
||||||
|
return self.lower() < other.lower()
|
||||||
|
|
||||||
|
def __gt__(self, other):
|
||||||
|
return self.lower() > other.lower()
|
||||||
|
|
||||||
|
def __eq__(self, other):
|
||||||
|
return self.lower() == other.lower()
|
||||||
|
|
||||||
|
def __ne__(self, other):
|
||||||
|
return self.lower() != other.lower()
|
||||||
|
|
||||||
|
def __hash__(self):
|
||||||
|
return hash(self.lower())
|
||||||
|
|
||||||
|
def __contains__(self, other):
|
||||||
|
return super().lower().__contains__(other.lower())
|
||||||
|
|
||||||
|
def in_(self, other):
|
||||||
|
"Does self appear in other?"
|
||||||
|
return self in FoldedCase(other)
|
||||||
|
|
||||||
|
# cache lower since it's likely to be called frequently.
|
||||||
|
@method_cache
|
||||||
|
def lower(self):
|
||||||
|
return super().lower()
|
||||||
|
|
||||||
|
def index(self, sub):
|
||||||
|
return self.lower().index(sub.lower())
|
||||||
|
|
||||||
|
def split(self, splitter=' ', maxsplit=0):
|
||||||
|
pattern = re.compile(re.escape(splitter), re.I)
|
||||||
|
return pattern.split(self, maxsplit)
|
||||||
|
|
||||||
|
|
||||||
|
# Python 3.8 compatibility
|
||||||
|
_unicode_trap = ExceptionTrap(UnicodeDecodeError)
|
||||||
|
|
||||||
|
|
||||||
|
@_unicode_trap.passes
|
||||||
|
def is_decodable(value):
|
||||||
|
r"""
|
||||||
|
Return True if the supplied value is decodable (using the default
|
||||||
|
encoding).
|
||||||
|
|
||||||
|
>>> is_decodable(b'\xff')
|
||||||
|
False
|
||||||
|
>>> is_decodable(b'\x32')
|
||||||
|
True
|
||||||
|
"""
|
||||||
|
value.decode()
|
||||||
|
|
||||||
|
|
||||||
|
def is_binary(value):
|
||||||
|
r"""
|
||||||
|
Return True if the value appears to be binary (that is, it's a byte
|
||||||
|
string and isn't decodable).
|
||||||
|
|
||||||
|
>>> is_binary(b'\xff')
|
||||||
|
True
|
||||||
|
>>> is_binary('\xff')
|
||||||
|
False
|
||||||
|
"""
|
||||||
|
return isinstance(value, bytes) and not is_decodable(value)
|
||||||
|
|
||||||
|
|
||||||
|
def trim(s):
|
||||||
|
r"""
|
||||||
|
Trim something like a docstring to remove the whitespace that
|
||||||
|
is common due to indentation and formatting.
|
||||||
|
|
||||||
|
>>> trim("\n\tfoo = bar\n\t\tbar = baz\n")
|
||||||
|
'foo = bar\n\tbar = baz'
|
||||||
|
"""
|
||||||
|
return textwrap.dedent(s).strip()
|
||||||
|
|
||||||
|
|
||||||
|
def wrap(s):
|
||||||
|
"""
|
||||||
|
Wrap lines of text, retaining existing newlines as
|
||||||
|
paragraph markers.
|
||||||
|
|
||||||
|
>>> print(wrap(lorem_ipsum))
|
||||||
|
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
|
||||||
|
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
|
||||||
|
minim veniam, quis nostrud exercitation ullamco laboris nisi ut
|
||||||
|
aliquip ex ea commodo consequat. Duis aute irure dolor in
|
||||||
|
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
|
||||||
|
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
|
||||||
|
culpa qui officia deserunt mollit anim id est laborum.
|
||||||
|
<BLANKLINE>
|
||||||
|
Curabitur pretium tincidunt lacus. Nulla gravida orci a odio. Nullam
|
||||||
|
varius, turpis et commodo pharetra, est eros bibendum elit, nec luctus
|
||||||
|
magna felis sollicitudin mauris. Integer in mauris eu nibh euismod
|
||||||
|
gravida. Duis ac tellus et risus vulputate vehicula. Donec lobortis
|
||||||
|
risus a elit. Etiam tempor. Ut ullamcorper, ligula eu tempor congue,
|
||||||
|
eros est euismod turpis, id tincidunt sapien risus a quam. Maecenas
|
||||||
|
fermentum consequat mi. Donec fermentum. Pellentesque malesuada nulla
|
||||||
|
a mi. Duis sapien sem, aliquet nec, commodo eget, consequat quis,
|
||||||
|
neque. Aliquam faucibus, elit ut dictum aliquet, felis nisl adipiscing
|
||||||
|
sapien, sed malesuada diam lacus eget erat. Cras mollis scelerisque
|
||||||
|
nunc. Nullam arcu. Aliquam consequat. Curabitur augue lorem, dapibus
|
||||||
|
quis, laoreet et, pretium ac, nisi. Aenean magna nisl, mollis quis,
|
||||||
|
molestie eu, feugiat in, orci. In hac habitasse platea dictumst.
|
||||||
|
"""
|
||||||
|
paragraphs = s.splitlines()
|
||||||
|
wrapped = ('\n'.join(textwrap.wrap(para)) for para in paragraphs)
|
||||||
|
return '\n\n'.join(wrapped)
|
||||||
|
|
||||||
|
|
||||||
|
def unwrap(s):
|
||||||
|
r"""
|
||||||
|
Given a multi-line string, return an unwrapped version.
|
||||||
|
|
||||||
|
>>> wrapped = wrap(lorem_ipsum)
|
||||||
|
>>> wrapped.count('\n')
|
||||||
|
20
|
||||||
|
>>> unwrapped = unwrap(wrapped)
|
||||||
|
>>> unwrapped.count('\n')
|
||||||
|
1
|
||||||
|
>>> print(unwrapped)
|
||||||
|
Lorem ipsum dolor sit amet, consectetur adipiscing ...
|
||||||
|
Curabitur pretium tincidunt lacus. Nulla gravida orci ...
|
||||||
|
|
||||||
|
"""
|
||||||
|
paragraphs = re.split(r'\n\n+', s)
|
||||||
|
cleaned = (para.replace('\n', ' ') for para in paragraphs)
|
||||||
|
return '\n'.join(cleaned)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
class Splitter(object):
|
||||||
|
"""object that will split a string with the given arguments for each call
|
||||||
|
|
||||||
|
>>> s = Splitter(',')
|
||||||
|
>>> s('hello, world, this is your, master calling')
|
||||||
|
['hello', ' world', ' this is your', ' master calling']
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, *args):
|
||||||
|
self.args = args
|
||||||
|
|
||||||
|
def __call__(self, s):
|
||||||
|
return s.split(*self.args)
|
||||||
|
|
||||||
|
|
||||||
|
def indent(string, prefix=' ' * 4):
|
||||||
|
"""
|
||||||
|
>>> indent('foo')
|
||||||
|
' foo'
|
||||||
|
"""
|
||||||
|
return prefix + string
|
||||||
|
|
||||||
|
|
||||||
|
class WordSet(tuple):
|
||||||
|
"""
|
||||||
|
Given an identifier, return the words that identifier represents,
|
||||||
|
whether in camel case, underscore-separated, etc.
|
||||||
|
|
||||||
|
>>> WordSet.parse("camelCase")
|
||||||
|
('camel', 'Case')
|
||||||
|
|
||||||
|
>>> WordSet.parse("under_sep")
|
||||||
|
('under', 'sep')
|
||||||
|
|
||||||
|
Acronyms should be retained
|
||||||
|
|
||||||
|
>>> WordSet.parse("firstSNL")
|
||||||
|
('first', 'SNL')
|
||||||
|
|
||||||
|
>>> WordSet.parse("you_and_I")
|
||||||
|
('you', 'and', 'I')
|
||||||
|
|
||||||
|
>>> WordSet.parse("A simple test")
|
||||||
|
('A', 'simple', 'test')
|
||||||
|
|
||||||
|
Multiple caps should not interfere with the first cap of another word.
|
||||||
|
|
||||||
|
>>> WordSet.parse("myABCClass")
|
||||||
|
('my', 'ABC', 'Class')
|
||||||
|
|
||||||
|
The result is a WordSet, so you can get the form you need.
|
||||||
|
|
||||||
|
>>> WordSet.parse("myABCClass").underscore_separated()
|
||||||
|
'my_ABC_Class'
|
||||||
|
|
||||||
|
>>> WordSet.parse('a-command').camel_case()
|
||||||
|
'ACommand'
|
||||||
|
|
||||||
|
>>> WordSet.parse('someIdentifier').lowered().space_separated()
|
||||||
|
'some identifier'
|
||||||
|
|
||||||
|
Slices of the result should return another WordSet.
|
||||||
|
|
||||||
|
>>> WordSet.parse('taken-out-of-context')[1:].underscore_separated()
|
||||||
|
'out_of_context'
|
||||||
|
|
||||||
|
>>> WordSet.from_class_name(WordSet()).lowered().space_separated()
|
||||||
|
'word set'
|
||||||
|
|
||||||
|
>>> example = WordSet.parse('figured it out')
|
||||||
|
>>> example.headless_camel_case()
|
||||||
|
'figuredItOut'
|
||||||
|
>>> example.dash_separated()
|
||||||
|
'figured-it-out'
|
||||||
|
|
||||||
|
"""
|
||||||
|
|
||||||
|
_pattern = re.compile('([A-Z]?[a-z]+)|([A-Z]+(?![a-z]))')
|
||||||
|
|
||||||
|
def capitalized(self):
|
||||||
|
return WordSet(word.capitalize() for word in self)
|
||||||
|
|
||||||
|
def lowered(self):
|
||||||
|
return WordSet(word.lower() for word in self)
|
||||||
|
|
||||||
|
def camel_case(self):
|
||||||
|
return ''.join(self.capitalized())
|
||||||
|
|
||||||
|
def headless_camel_case(self):
|
||||||
|
words = iter(self)
|
||||||
|
first = next(words).lower()
|
||||||
|
new_words = itertools.chain((first,), WordSet(words).camel_case())
|
||||||
|
return ''.join(new_words)
|
||||||
|
|
||||||
|
def underscore_separated(self):
|
||||||
|
return '_'.join(self)
|
||||||
|
|
||||||
|
def dash_separated(self):
|
||||||
|
return '-'.join(self)
|
||||||
|
|
||||||
|
def space_separated(self):
|
||||||
|
return ' '.join(self)
|
||||||
|
|
||||||
|
def trim_right(self, item):
|
||||||
|
"""
|
||||||
|
Remove the item from the end of the set.
|
||||||
|
|
||||||
|
>>> WordSet.parse('foo bar').trim_right('foo')
|
||||||
|
('foo', 'bar')
|
||||||
|
>>> WordSet.parse('foo bar').trim_right('bar')
|
||||||
|
('foo',)
|
||||||
|
>>> WordSet.parse('').trim_right('bar')
|
||||||
|
()
|
||||||
|
"""
|
||||||
|
return self[:-1] if self and self[-1] == item else self
|
||||||
|
|
||||||
|
def trim_left(self, item):
|
||||||
|
"""
|
||||||
|
Remove the item from the beginning of the set.
|
||||||
|
|
||||||
|
>>> WordSet.parse('foo bar').trim_left('foo')
|
||||||
|
('bar',)
|
||||||
|
>>> WordSet.parse('foo bar').trim_left('bar')
|
||||||
|
('foo', 'bar')
|
||||||
|
>>> WordSet.parse('').trim_left('bar')
|
||||||
|
()
|
||||||
|
"""
|
||||||
|
return self[1:] if self and self[0] == item else self
|
||||||
|
|
||||||
|
def trim(self, item):
|
||||||
|
"""
|
||||||
|
>>> WordSet.parse('foo bar').trim('foo')
|
||||||
|
('bar',)
|
||||||
|
"""
|
||||||
|
return self.trim_left(item).trim_right(item)
|
||||||
|
|
||||||
|
def __getitem__(self, item):
|
||||||
|
result = super(WordSet, self).__getitem__(item)
|
||||||
|
if isinstance(item, slice):
|
||||||
|
result = WordSet(result)
|
||||||
|
return result
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
def parse(cls, identifier):
|
||||||
|
matches = cls._pattern.finditer(identifier)
|
||||||
|
return WordSet(match.group(0) for match in matches)
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
def from_class_name(cls, subject):
|
||||||
|
return cls.parse(subject.__class__.__name__)
|
||||||
|
|
||||||
|
|
||||||
|
# for backward compatibility
|
||||||
|
words = WordSet.parse
|
||||||
|
|
||||||
|
|
||||||
|
def simple_html_strip(s):
|
||||||
|
r"""
|
||||||
|
Remove HTML from the string `s`.
|
||||||
|
|
||||||
|
>>> str(simple_html_strip(''))
|
||||||
|
''
|
||||||
|
|
||||||
|
>>> print(simple_html_strip('A <bold>stormy</bold> day in paradise'))
|
||||||
|
A stormy day in paradise
|
||||||
|
|
||||||
|
>>> print(simple_html_strip('Somebody <!-- do not --> tell the truth.'))
|
||||||
|
Somebody tell the truth.
|
||||||
|
|
||||||
|
>>> print(simple_html_strip('What about<br/>\nmultiple lines?'))
|
||||||
|
What about
|
||||||
|
multiple lines?
|
||||||
|
"""
|
||||||
|
html_stripper = re.compile('(<!--.*?-->)|(<[^>]*>)|([^<]+)', re.DOTALL)
|
||||||
|
texts = (match.group(3) or '' for match in html_stripper.finditer(s))
|
||||||
|
return ''.join(texts)
|
||||||
|
|
||||||
|
|
||||||
|
class SeparatedValues(str):
|
||||||
|
"""
|
||||||
|
A string separated by a separator. Overrides __iter__ for getting
|
||||||
|
the values.
|
||||||
|
|
||||||
|
>>> list(SeparatedValues('a,b,c'))
|
||||||
|
['a', 'b', 'c']
|
||||||
|
|
||||||
|
Whitespace is stripped and empty values are discarded.
|
||||||
|
|
||||||
|
>>> list(SeparatedValues(' a, b , c, '))
|
||||||
|
['a', 'b', 'c']
|
||||||
|
"""
|
||||||
|
|
||||||
|
separator = ','
|
||||||
|
|
||||||
|
def __iter__(self):
|
||||||
|
parts = self.split(self.separator)
|
||||||
|
return filter(None, (part.strip() for part in parts))
|
||||||
|
|
||||||
|
|
||||||
|
class Stripper:
|
||||||
|
r"""
|
||||||
|
Given a series of lines, find the common prefix and strip it from them.
|
||||||
|
|
||||||
|
>>> lines = [
|
||||||
|
... 'abcdefg\n',
|
||||||
|
... 'abc\n',
|
||||||
|
... 'abcde\n',
|
||||||
|
... ]
|
||||||
|
>>> res = Stripper.strip_prefix(lines)
|
||||||
|
>>> res.prefix
|
||||||
|
'abc'
|
||||||
|
>>> list(res.lines)
|
||||||
|
['defg\n', '\n', 'de\n']
|
||||||
|
|
||||||
|
If no prefix is common, nothing should be stripped.
|
||||||
|
|
||||||
|
>>> lines = [
|
||||||
|
... 'abcd\n',
|
||||||
|
... '1234\n',
|
||||||
|
... ]
|
||||||
|
>>> res = Stripper.strip_prefix(lines)
|
||||||
|
>>> res.prefix = ''
|
||||||
|
>>> list(res.lines)
|
||||||
|
['abcd\n', '1234\n']
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, prefix, lines):
|
||||||
|
self.prefix = prefix
|
||||||
|
self.lines = map(self, lines)
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
def strip_prefix(cls, lines):
|
||||||
|
prefix_lines, lines = itertools.tee(lines)
|
||||||
|
prefix = functools.reduce(cls.common_prefix, prefix_lines)
|
||||||
|
return cls(prefix, lines)
|
||||||
|
|
||||||
|
def __call__(self, line):
|
||||||
|
if not self.prefix:
|
||||||
|
return line
|
||||||
|
null, prefix, rest = line.partition(self.prefix)
|
||||||
|
return rest
|
||||||
|
|
||||||
|
@staticmethod
|
||||||
|
def common_prefix(s1, s2):
|
||||||
|
"""
|
||||||
|
Return the common prefix of two lines.
|
||||||
|
"""
|
||||||
|
index = min(len(s1), len(s2))
|
||||||
|
while s1[:index] != s2[:index]:
|
||||||
|
index -= 1
|
||||||
|
return s1[:index]
|
||||||
|
|
||||||
|
|
||||||
|
def remove_prefix(text, prefix):
|
||||||
|
"""
|
||||||
|
Remove the prefix from the text if it exists.
|
||||||
|
|
||||||
|
>>> remove_prefix('underwhelming performance', 'underwhelming ')
|
||||||
|
'performance'
|
||||||
|
|
||||||
|
>>> remove_prefix('something special', 'sample')
|
||||||
|
'something special'
|
||||||
|
"""
|
||||||
|
null, prefix, rest = text.rpartition(prefix)
|
||||||
|
return rest
|
||||||
|
|
||||||
|
|
||||||
|
def remove_suffix(text, suffix):
|
||||||
|
"""
|
||||||
|
Remove the suffix from the text if it exists.
|
||||||
|
|
||||||
|
>>> remove_suffix('name.git', '.git')
|
||||||
|
'name'
|
||||||
|
|
||||||
|
>>> remove_suffix('something special', 'sample')
|
||||||
|
'something special'
|
||||||
|
"""
|
||||||
|
rest, suffix, null = text.partition(suffix)
|
||||||
|
return rest
|
||||||
|
|
||||||
|
|
||||||
|
def normalize_newlines(text):
|
||||||
|
r"""
|
||||||
|
Replace alternate newlines with the canonical newline.
|
||||||
|
|
||||||
|
>>> normalize_newlines('Lorem Ipsum\u2029')
|
||||||
|
'Lorem Ipsum\n'
|
||||||
|
>>> normalize_newlines('Lorem Ipsum\r\n')
|
||||||
|
'Lorem Ipsum\n'
|
||||||
|
>>> normalize_newlines('Lorem Ipsum\x85')
|
||||||
|
'Lorem Ipsum\n'
|
||||||
|
"""
|
||||||
|
newlines = ['\r\n', '\r', '\n', '\u0085', '\u2028', '\u2029']
|
||||||
|
pattern = '|'.join(newlines)
|
||||||
|
return re.sub(pattern, '\n', text)
|
||||||
|
|
||||||
|
|
||||||
|
def _nonblank(str):
|
||||||
|
return str and not str.startswith('#')
|
||||||
|
|
||||||
|
|
||||||
|
@functools.singledispatch
|
||||||
|
def yield_lines(iterable):
|
||||||
|
r"""
|
||||||
|
Yield valid lines of a string or iterable.
|
||||||
|
|
||||||
|
>>> list(yield_lines(''))
|
||||||
|
[]
|
||||||
|
>>> list(yield_lines(['foo', 'bar']))
|
||||||
|
['foo', 'bar']
|
||||||
|
>>> list(yield_lines('foo\nbar'))
|
||||||
|
['foo', 'bar']
|
||||||
|
>>> list(yield_lines('\nfoo\n#bar\nbaz #comment'))
|
||||||
|
['foo', 'baz #comment']
|
||||||
|
>>> list(yield_lines(['foo\nbar', 'baz', 'bing\n\n\n']))
|
||||||
|
['foo', 'bar', 'baz', 'bing']
|
||||||
|
"""
|
||||||
|
return itertools.chain.from_iterable(map(yield_lines, iterable))
|
||||||
|
|
||||||
|
|
||||||
|
@yield_lines.register(str)
|
||||||
|
def _(text):
|
||||||
|
return filter(_nonblank, map(str.strip, text.splitlines()))
|
||||||
|
|
||||||
|
|
||||||
|
def drop_comment(line):
|
||||||
|
"""
|
||||||
|
Drop comments.
|
||||||
|
|
||||||
|
>>> drop_comment('foo # bar')
|
||||||
|
'foo'
|
||||||
|
|
||||||
|
A hash without a space may be in a URL.
|
||||||
|
|
||||||
|
>>> drop_comment('http://example.com/foo#bar')
|
||||||
|
'http://example.com/foo#bar'
|
||||||
|
"""
|
||||||
|
return line.partition(' #')[0]
|
||||||
|
|
||||||
|
|
||||||
|
def join_continuation(lines):
|
||||||
|
r"""
|
||||||
|
Join lines continued by a trailing backslash.
|
||||||
|
|
||||||
|
>>> list(join_continuation(['foo \\', 'bar', 'baz']))
|
||||||
|
['foobar', 'baz']
|
||||||
|
>>> list(join_continuation(['foo \\', 'bar', 'baz']))
|
||||||
|
['foobar', 'baz']
|
||||||
|
>>> list(join_continuation(['foo \\', 'bar \\', 'baz']))
|
||||||
|
['foobarbaz']
|
||||||
|
|
||||||
|
Not sure why, but...
|
||||||
|
The character preceeding the backslash is also elided.
|
||||||
|
|
||||||
|
>>> list(join_continuation(['goo\\', 'dly']))
|
||||||
|
['godly']
|
||||||
|
|
||||||
|
A terrible idea, but...
|
||||||
|
If no line is available to continue, suppress the lines.
|
||||||
|
|
||||||
|
>>> list(join_continuation(['foo', 'bar\\', 'baz\\']))
|
||||||
|
['foo']
|
||||||
|
"""
|
||||||
|
lines = iter(lines)
|
||||||
|
for item in lines:
|
||||||
|
while item.endswith('\\'):
|
||||||
|
try:
|
||||||
|
item = item[:-2].strip() + next(lines)
|
||||||
|
except StopIteration:
|
||||||
|
return
|
||||||
|
yield item
|
||||||
Binary file not shown.
|
|
@ -0,0 +1,6 @@
|
||||||
|
"""More routines for operating on iterables, beyond itertools"""
|
||||||
|
|
||||||
|
from .more import * # noqa
|
||||||
|
from .recipes import * # noqa
|
||||||
|
|
||||||
|
__version__ = '10.2.0'
|
||||||
|
|
@ -0,0 +1,2 @@
|
||||||
|
from .more import *
|
||||||
|
from .recipes import *
|
||||||
Binary file not shown.
Binary file not shown.
Binary file not shown.
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,695 @@
|
||||||
|
"""Stubs for more_itertools.more"""
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from types import TracebackType
|
||||||
|
from typing import (
|
||||||
|
Any,
|
||||||
|
Callable,
|
||||||
|
Container,
|
||||||
|
ContextManager,
|
||||||
|
Generic,
|
||||||
|
Hashable,
|
||||||
|
Iterable,
|
||||||
|
Iterator,
|
||||||
|
overload,
|
||||||
|
Reversible,
|
||||||
|
Sequence,
|
||||||
|
Sized,
|
||||||
|
Type,
|
||||||
|
TypeVar,
|
||||||
|
type_check_only,
|
||||||
|
)
|
||||||
|
from typing_extensions import Protocol
|
||||||
|
|
||||||
|
# Type and type variable definitions
|
||||||
|
_T = TypeVar('_T')
|
||||||
|
_T1 = TypeVar('_T1')
|
||||||
|
_T2 = TypeVar('_T2')
|
||||||
|
_U = TypeVar('_U')
|
||||||
|
_V = TypeVar('_V')
|
||||||
|
_W = TypeVar('_W')
|
||||||
|
_T_co = TypeVar('_T_co', covariant=True)
|
||||||
|
_GenFn = TypeVar('_GenFn', bound=Callable[..., Iterator[Any]])
|
||||||
|
_Raisable = BaseException | Type[BaseException]
|
||||||
|
|
||||||
|
@type_check_only
|
||||||
|
class _SizedIterable(Protocol[_T_co], Sized, Iterable[_T_co]): ...
|
||||||
|
|
||||||
|
@type_check_only
|
||||||
|
class _SizedReversible(Protocol[_T_co], Sized, Reversible[_T_co]): ...
|
||||||
|
|
||||||
|
@type_check_only
|
||||||
|
class _SupportsSlicing(Protocol[_T_co]):
|
||||||
|
def __getitem__(self, __k: slice) -> _T_co: ...
|
||||||
|
|
||||||
|
def chunked(
|
||||||
|
iterable: Iterable[_T], n: int | None, strict: bool = ...
|
||||||
|
) -> Iterator[list[_T]]: ...
|
||||||
|
@overload
|
||||||
|
def first(iterable: Iterable[_T]) -> _T: ...
|
||||||
|
@overload
|
||||||
|
def first(iterable: Iterable[_T], default: _U) -> _T | _U: ...
|
||||||
|
@overload
|
||||||
|
def last(iterable: Iterable[_T]) -> _T: ...
|
||||||
|
@overload
|
||||||
|
def last(iterable: Iterable[_T], default: _U) -> _T | _U: ...
|
||||||
|
@overload
|
||||||
|
def nth_or_last(iterable: Iterable[_T], n: int) -> _T: ...
|
||||||
|
@overload
|
||||||
|
def nth_or_last(iterable: Iterable[_T], n: int, default: _U) -> _T | _U: ...
|
||||||
|
|
||||||
|
class peekable(Generic[_T], Iterator[_T]):
|
||||||
|
def __init__(self, iterable: Iterable[_T]) -> None: ...
|
||||||
|
def __iter__(self) -> peekable[_T]: ...
|
||||||
|
def __bool__(self) -> bool: ...
|
||||||
|
@overload
|
||||||
|
def peek(self) -> _T: ...
|
||||||
|
@overload
|
||||||
|
def peek(self, default: _U) -> _T | _U: ...
|
||||||
|
def prepend(self, *items: _T) -> None: ...
|
||||||
|
def __next__(self) -> _T: ...
|
||||||
|
@overload
|
||||||
|
def __getitem__(self, index: int) -> _T: ...
|
||||||
|
@overload
|
||||||
|
def __getitem__(self, index: slice) -> list[_T]: ...
|
||||||
|
|
||||||
|
def consumer(func: _GenFn) -> _GenFn: ...
|
||||||
|
def ilen(iterable: Iterable[_T]) -> int: ...
|
||||||
|
def iterate(func: Callable[[_T], _T], start: _T) -> Iterator[_T]: ...
|
||||||
|
def with_iter(
|
||||||
|
context_manager: ContextManager[Iterable[_T]],
|
||||||
|
) -> Iterator[_T]: ...
|
||||||
|
def one(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
too_short: _Raisable | None = ...,
|
||||||
|
too_long: _Raisable | None = ...,
|
||||||
|
) -> _T: ...
|
||||||
|
def raise_(exception: _Raisable, *args: Any) -> None: ...
|
||||||
|
def strictly_n(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
n: int,
|
||||||
|
too_short: _GenFn | None = ...,
|
||||||
|
too_long: _GenFn | None = ...,
|
||||||
|
) -> list[_T]: ...
|
||||||
|
def distinct_permutations(
|
||||||
|
iterable: Iterable[_T], r: int | None = ...
|
||||||
|
) -> Iterator[tuple[_T, ...]]: ...
|
||||||
|
def intersperse(
|
||||||
|
e: _U, iterable: Iterable[_T], n: int = ...
|
||||||
|
) -> Iterator[_T | _U]: ...
|
||||||
|
def unique_to_each(*iterables: Iterable[_T]) -> list[list[_T]]: ...
|
||||||
|
@overload
|
||||||
|
def windowed(
|
||||||
|
seq: Iterable[_T], n: int, *, step: int = ...
|
||||||
|
) -> Iterator[tuple[_T | None, ...]]: ...
|
||||||
|
@overload
|
||||||
|
def windowed(
|
||||||
|
seq: Iterable[_T], n: int, fillvalue: _U, step: int = ...
|
||||||
|
) -> Iterator[tuple[_T | _U, ...]]: ...
|
||||||
|
def substrings(iterable: Iterable[_T]) -> Iterator[tuple[_T, ...]]: ...
|
||||||
|
def substrings_indexes(
|
||||||
|
seq: Sequence[_T], reverse: bool = ...
|
||||||
|
) -> Iterator[tuple[Sequence[_T], int, int]]: ...
|
||||||
|
|
||||||
|
class bucket(Generic[_T, _U], Container[_U]):
|
||||||
|
def __init__(
|
||||||
|
self,
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
key: Callable[[_T], _U],
|
||||||
|
validator: Callable[[_U], object] | None = ...,
|
||||||
|
) -> None: ...
|
||||||
|
def __contains__(self, value: object) -> bool: ...
|
||||||
|
def __iter__(self) -> Iterator[_U]: ...
|
||||||
|
def __getitem__(self, value: object) -> Iterator[_T]: ...
|
||||||
|
|
||||||
|
def spy(
|
||||||
|
iterable: Iterable[_T], n: int = ...
|
||||||
|
) -> tuple[list[_T], Iterator[_T]]: ...
|
||||||
|
def interleave(*iterables: Iterable[_T]) -> Iterator[_T]: ...
|
||||||
|
def interleave_longest(*iterables: Iterable[_T]) -> Iterator[_T]: ...
|
||||||
|
def interleave_evenly(
|
||||||
|
iterables: list[Iterable[_T]], lengths: list[int] | None = ...
|
||||||
|
) -> Iterator[_T]: ...
|
||||||
|
def collapse(
|
||||||
|
iterable: Iterable[Any],
|
||||||
|
base_type: type | None = ...,
|
||||||
|
levels: int | None = ...,
|
||||||
|
) -> Iterator[Any]: ...
|
||||||
|
@overload
|
||||||
|
def side_effect(
|
||||||
|
func: Callable[[_T], object],
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
chunk_size: None = ...,
|
||||||
|
before: Callable[[], object] | None = ...,
|
||||||
|
after: Callable[[], object] | None = ...,
|
||||||
|
) -> Iterator[_T]: ...
|
||||||
|
@overload
|
||||||
|
def side_effect(
|
||||||
|
func: Callable[[list[_T]], object],
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
chunk_size: int,
|
||||||
|
before: Callable[[], object] | None = ...,
|
||||||
|
after: Callable[[], object] | None = ...,
|
||||||
|
) -> Iterator[_T]: ...
|
||||||
|
def sliced(
|
||||||
|
seq: _SupportsSlicing[_T], n: int, strict: bool = ...
|
||||||
|
) -> Iterator[_T]: ...
|
||||||
|
def split_at(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
pred: Callable[[_T], object],
|
||||||
|
maxsplit: int = ...,
|
||||||
|
keep_separator: bool = ...,
|
||||||
|
) -> Iterator[list[_T]]: ...
|
||||||
|
def split_before(
|
||||||
|
iterable: Iterable[_T], pred: Callable[[_T], object], maxsplit: int = ...
|
||||||
|
) -> Iterator[list[_T]]: ...
|
||||||
|
def split_after(
|
||||||
|
iterable: Iterable[_T], pred: Callable[[_T], object], maxsplit: int = ...
|
||||||
|
) -> Iterator[list[_T]]: ...
|
||||||
|
def split_when(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
pred: Callable[[_T, _T], object],
|
||||||
|
maxsplit: int = ...,
|
||||||
|
) -> Iterator[list[_T]]: ...
|
||||||
|
def split_into(
|
||||||
|
iterable: Iterable[_T], sizes: Iterable[int | None]
|
||||||
|
) -> Iterator[list[_T]]: ...
|
||||||
|
@overload
|
||||||
|
def padded(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
*,
|
||||||
|
n: int | None = ...,
|
||||||
|
next_multiple: bool = ...,
|
||||||
|
) -> Iterator[_T | None]: ...
|
||||||
|
@overload
|
||||||
|
def padded(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
fillvalue: _U,
|
||||||
|
n: int | None = ...,
|
||||||
|
next_multiple: bool = ...,
|
||||||
|
) -> Iterator[_T | _U]: ...
|
||||||
|
@overload
|
||||||
|
def repeat_last(iterable: Iterable[_T]) -> Iterator[_T]: ...
|
||||||
|
@overload
|
||||||
|
def repeat_last(iterable: Iterable[_T], default: _U) -> Iterator[_T | _U]: ...
|
||||||
|
def distribute(n: int, iterable: Iterable[_T]) -> list[Iterator[_T]]: ...
|
||||||
|
@overload
|
||||||
|
def stagger(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
offsets: _SizedIterable[int] = ...,
|
||||||
|
longest: bool = ...,
|
||||||
|
) -> Iterator[tuple[_T | None, ...]]: ...
|
||||||
|
@overload
|
||||||
|
def stagger(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
offsets: _SizedIterable[int] = ...,
|
||||||
|
longest: bool = ...,
|
||||||
|
fillvalue: _U = ...,
|
||||||
|
) -> Iterator[tuple[_T | _U, ...]]: ...
|
||||||
|
|
||||||
|
class UnequalIterablesError(ValueError):
|
||||||
|
def __init__(self, details: tuple[int, int, int] | None = ...) -> None: ...
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def zip_equal(__iter1: Iterable[_T1]) -> Iterator[tuple[_T1]]: ...
|
||||||
|
@overload
|
||||||
|
def zip_equal(
|
||||||
|
__iter1: Iterable[_T1], __iter2: Iterable[_T2]
|
||||||
|
) -> Iterator[tuple[_T1, _T2]]: ...
|
||||||
|
@overload
|
||||||
|
def zip_equal(
|
||||||
|
__iter1: Iterable[_T],
|
||||||
|
__iter2: Iterable[_T],
|
||||||
|
__iter3: Iterable[_T],
|
||||||
|
*iterables: Iterable[_T],
|
||||||
|
) -> Iterator[tuple[_T, ...]]: ...
|
||||||
|
@overload
|
||||||
|
def zip_offset(
|
||||||
|
__iter1: Iterable[_T1],
|
||||||
|
*,
|
||||||
|
offsets: _SizedIterable[int],
|
||||||
|
longest: bool = ...,
|
||||||
|
fillvalue: None = None,
|
||||||
|
) -> Iterator[tuple[_T1 | None]]: ...
|
||||||
|
@overload
|
||||||
|
def zip_offset(
|
||||||
|
__iter1: Iterable[_T1],
|
||||||
|
__iter2: Iterable[_T2],
|
||||||
|
*,
|
||||||
|
offsets: _SizedIterable[int],
|
||||||
|
longest: bool = ...,
|
||||||
|
fillvalue: None = None,
|
||||||
|
) -> Iterator[tuple[_T1 | None, _T2 | None]]: ...
|
||||||
|
@overload
|
||||||
|
def zip_offset(
|
||||||
|
__iter1: Iterable[_T],
|
||||||
|
__iter2: Iterable[_T],
|
||||||
|
__iter3: Iterable[_T],
|
||||||
|
*iterables: Iterable[_T],
|
||||||
|
offsets: _SizedIterable[int],
|
||||||
|
longest: bool = ...,
|
||||||
|
fillvalue: None = None,
|
||||||
|
) -> Iterator[tuple[_T | None, ...]]: ...
|
||||||
|
@overload
|
||||||
|
def zip_offset(
|
||||||
|
__iter1: Iterable[_T1],
|
||||||
|
*,
|
||||||
|
offsets: _SizedIterable[int],
|
||||||
|
longest: bool = ...,
|
||||||
|
fillvalue: _U,
|
||||||
|
) -> Iterator[tuple[_T1 | _U]]: ...
|
||||||
|
@overload
|
||||||
|
def zip_offset(
|
||||||
|
__iter1: Iterable[_T1],
|
||||||
|
__iter2: Iterable[_T2],
|
||||||
|
*,
|
||||||
|
offsets: _SizedIterable[int],
|
||||||
|
longest: bool = ...,
|
||||||
|
fillvalue: _U,
|
||||||
|
) -> Iterator[tuple[_T1 | _U, _T2 | _U]]: ...
|
||||||
|
@overload
|
||||||
|
def zip_offset(
|
||||||
|
__iter1: Iterable[_T],
|
||||||
|
__iter2: Iterable[_T],
|
||||||
|
__iter3: Iterable[_T],
|
||||||
|
*iterables: Iterable[_T],
|
||||||
|
offsets: _SizedIterable[int],
|
||||||
|
longest: bool = ...,
|
||||||
|
fillvalue: _U,
|
||||||
|
) -> Iterator[tuple[_T | _U, ...]]: ...
|
||||||
|
def sort_together(
|
||||||
|
iterables: Iterable[Iterable[_T]],
|
||||||
|
key_list: Iterable[int] = ...,
|
||||||
|
key: Callable[..., Any] | None = ...,
|
||||||
|
reverse: bool = ...,
|
||||||
|
) -> list[tuple[_T, ...]]: ...
|
||||||
|
def unzip(iterable: Iterable[Sequence[_T]]) -> tuple[Iterator[_T], ...]: ...
|
||||||
|
def divide(n: int, iterable: Iterable[_T]) -> list[Iterator[_T]]: ...
|
||||||
|
def always_iterable(
|
||||||
|
obj: object,
|
||||||
|
base_type: type | tuple[type | tuple[Any, ...], ...] | None = ...,
|
||||||
|
) -> Iterator[Any]: ...
|
||||||
|
def adjacent(
|
||||||
|
predicate: Callable[[_T], bool],
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
distance: int = ...,
|
||||||
|
) -> Iterator[tuple[bool, _T]]: ...
|
||||||
|
@overload
|
||||||
|
def groupby_transform(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
keyfunc: None = None,
|
||||||
|
valuefunc: None = None,
|
||||||
|
reducefunc: None = None,
|
||||||
|
) -> Iterator[tuple[_T, Iterator[_T]]]: ...
|
||||||
|
@overload
|
||||||
|
def groupby_transform(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
keyfunc: Callable[[_T], _U],
|
||||||
|
valuefunc: None,
|
||||||
|
reducefunc: None,
|
||||||
|
) -> Iterator[tuple[_U, Iterator[_T]]]: ...
|
||||||
|
@overload
|
||||||
|
def groupby_transform(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
keyfunc: None,
|
||||||
|
valuefunc: Callable[[_T], _V],
|
||||||
|
reducefunc: None,
|
||||||
|
) -> Iterable[tuple[_T, Iterable[_V]]]: ...
|
||||||
|
@overload
|
||||||
|
def groupby_transform(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
keyfunc: Callable[[_T], _U],
|
||||||
|
valuefunc: Callable[[_T], _V],
|
||||||
|
reducefunc: None,
|
||||||
|
) -> Iterable[tuple[_U, Iterator[_V]]]: ...
|
||||||
|
@overload
|
||||||
|
def groupby_transform(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
keyfunc: None,
|
||||||
|
valuefunc: None,
|
||||||
|
reducefunc: Callable[[Iterator[_T]], _W],
|
||||||
|
) -> Iterable[tuple[_T, _W]]: ...
|
||||||
|
@overload
|
||||||
|
def groupby_transform(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
keyfunc: Callable[[_T], _U],
|
||||||
|
valuefunc: None,
|
||||||
|
reducefunc: Callable[[Iterator[_T]], _W],
|
||||||
|
) -> Iterable[tuple[_U, _W]]: ...
|
||||||
|
@overload
|
||||||
|
def groupby_transform(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
keyfunc: None,
|
||||||
|
valuefunc: Callable[[_T], _V],
|
||||||
|
reducefunc: Callable[[Iterable[_V]], _W],
|
||||||
|
) -> Iterable[tuple[_T, _W]]: ...
|
||||||
|
@overload
|
||||||
|
def groupby_transform(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
keyfunc: Callable[[_T], _U],
|
||||||
|
valuefunc: Callable[[_T], _V],
|
||||||
|
reducefunc: Callable[[Iterable[_V]], _W],
|
||||||
|
) -> Iterable[tuple[_U, _W]]: ...
|
||||||
|
|
||||||
|
class numeric_range(Generic[_T, _U], Sequence[_T], Hashable, Reversible[_T]):
|
||||||
|
@overload
|
||||||
|
def __init__(self, __stop: _T) -> None: ...
|
||||||
|
@overload
|
||||||
|
def __init__(self, __start: _T, __stop: _T) -> None: ...
|
||||||
|
@overload
|
||||||
|
def __init__(self, __start: _T, __stop: _T, __step: _U) -> None: ...
|
||||||
|
def __bool__(self) -> bool: ...
|
||||||
|
def __contains__(self, elem: object) -> bool: ...
|
||||||
|
def __eq__(self, other: object) -> bool: ...
|
||||||
|
@overload
|
||||||
|
def __getitem__(self, key: int) -> _T: ...
|
||||||
|
@overload
|
||||||
|
def __getitem__(self, key: slice) -> numeric_range[_T, _U]: ...
|
||||||
|
def __hash__(self) -> int: ...
|
||||||
|
def __iter__(self) -> Iterator[_T]: ...
|
||||||
|
def __len__(self) -> int: ...
|
||||||
|
def __reduce__(
|
||||||
|
self,
|
||||||
|
) -> tuple[Type[numeric_range[_T, _U]], tuple[_T, _T, _U]]: ...
|
||||||
|
def __repr__(self) -> str: ...
|
||||||
|
def __reversed__(self) -> Iterator[_T]: ...
|
||||||
|
def count(self, value: _T) -> int: ...
|
||||||
|
def index(self, value: _T) -> int: ... # type: ignore
|
||||||
|
|
||||||
|
def count_cycle(
|
||||||
|
iterable: Iterable[_T], n: int | None = ...
|
||||||
|
) -> Iterable[tuple[int, _T]]: ...
|
||||||
|
def mark_ends(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
) -> Iterable[tuple[bool, bool, _T]]: ...
|
||||||
|
def locate(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
pred: Callable[..., Any] = ...,
|
||||||
|
window_size: int | None = ...,
|
||||||
|
) -> Iterator[int]: ...
|
||||||
|
def lstrip(
|
||||||
|
iterable: Iterable[_T], pred: Callable[[_T], object]
|
||||||
|
) -> Iterator[_T]: ...
|
||||||
|
def rstrip(
|
||||||
|
iterable: Iterable[_T], pred: Callable[[_T], object]
|
||||||
|
) -> Iterator[_T]: ...
|
||||||
|
def strip(
|
||||||
|
iterable: Iterable[_T], pred: Callable[[_T], object]
|
||||||
|
) -> Iterator[_T]: ...
|
||||||
|
|
||||||
|
class islice_extended(Generic[_T], Iterator[_T]):
|
||||||
|
def __init__(self, iterable: Iterable[_T], *args: int | None) -> None: ...
|
||||||
|
def __iter__(self) -> islice_extended[_T]: ...
|
||||||
|
def __next__(self) -> _T: ...
|
||||||
|
def __getitem__(self, index: slice) -> islice_extended[_T]: ...
|
||||||
|
|
||||||
|
def always_reversible(iterable: Iterable[_T]) -> Iterator[_T]: ...
|
||||||
|
def consecutive_groups(
|
||||||
|
iterable: Iterable[_T], ordering: Callable[[_T], int] = ...
|
||||||
|
) -> Iterator[Iterator[_T]]: ...
|
||||||
|
@overload
|
||||||
|
def difference(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
func: Callable[[_T, _T], _U] = ...,
|
||||||
|
*,
|
||||||
|
initial: None = ...,
|
||||||
|
) -> Iterator[_T | _U]: ...
|
||||||
|
@overload
|
||||||
|
def difference(
|
||||||
|
iterable: Iterable[_T], func: Callable[[_T, _T], _U] = ..., *, initial: _U
|
||||||
|
) -> Iterator[_U]: ...
|
||||||
|
|
||||||
|
class SequenceView(Generic[_T], Sequence[_T]):
|
||||||
|
def __init__(self, target: Sequence[_T]) -> None: ...
|
||||||
|
@overload
|
||||||
|
def __getitem__(self, index: int) -> _T: ...
|
||||||
|
@overload
|
||||||
|
def __getitem__(self, index: slice) -> Sequence[_T]: ...
|
||||||
|
def __len__(self) -> int: ...
|
||||||
|
|
||||||
|
class seekable(Generic[_T], Iterator[_T]):
|
||||||
|
def __init__(
|
||||||
|
self, iterable: Iterable[_T], maxlen: int | None = ...
|
||||||
|
) -> None: ...
|
||||||
|
def __iter__(self) -> seekable[_T]: ...
|
||||||
|
def __next__(self) -> _T: ...
|
||||||
|
def __bool__(self) -> bool: ...
|
||||||
|
@overload
|
||||||
|
def peek(self) -> _T: ...
|
||||||
|
@overload
|
||||||
|
def peek(self, default: _U) -> _T | _U: ...
|
||||||
|
def elements(self) -> SequenceView[_T]: ...
|
||||||
|
def seek(self, index: int) -> None: ...
|
||||||
|
def relative_seek(self, count: int) -> None: ...
|
||||||
|
|
||||||
|
class run_length:
|
||||||
|
@staticmethod
|
||||||
|
def encode(iterable: Iterable[_T]) -> Iterator[tuple[_T, int]]: ...
|
||||||
|
@staticmethod
|
||||||
|
def decode(iterable: Iterable[tuple[_T, int]]) -> Iterator[_T]: ...
|
||||||
|
|
||||||
|
def exactly_n(
|
||||||
|
iterable: Iterable[_T], n: int, predicate: Callable[[_T], object] = ...
|
||||||
|
) -> bool: ...
|
||||||
|
def circular_shifts(iterable: Iterable[_T]) -> list[tuple[_T, ...]]: ...
|
||||||
|
def make_decorator(
|
||||||
|
wrapping_func: Callable[..., _U], result_index: int = ...
|
||||||
|
) -> Callable[..., Callable[[Callable[..., Any]], Callable[..., _U]]]: ...
|
||||||
|
@overload
|
||||||
|
def map_reduce(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
keyfunc: Callable[[_T], _U],
|
||||||
|
valuefunc: None = ...,
|
||||||
|
reducefunc: None = ...,
|
||||||
|
) -> dict[_U, list[_T]]: ...
|
||||||
|
@overload
|
||||||
|
def map_reduce(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
keyfunc: Callable[[_T], _U],
|
||||||
|
valuefunc: Callable[[_T], _V],
|
||||||
|
reducefunc: None = ...,
|
||||||
|
) -> dict[_U, list[_V]]: ...
|
||||||
|
@overload
|
||||||
|
def map_reduce(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
keyfunc: Callable[[_T], _U],
|
||||||
|
valuefunc: None = ...,
|
||||||
|
reducefunc: Callable[[list[_T]], _W] = ...,
|
||||||
|
) -> dict[_U, _W]: ...
|
||||||
|
@overload
|
||||||
|
def map_reduce(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
keyfunc: Callable[[_T], _U],
|
||||||
|
valuefunc: Callable[[_T], _V],
|
||||||
|
reducefunc: Callable[[list[_V]], _W],
|
||||||
|
) -> dict[_U, _W]: ...
|
||||||
|
def rlocate(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
pred: Callable[..., object] = ...,
|
||||||
|
window_size: int | None = ...,
|
||||||
|
) -> Iterator[int]: ...
|
||||||
|
def replace(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
pred: Callable[..., object],
|
||||||
|
substitutes: Iterable[_U],
|
||||||
|
count: int | None = ...,
|
||||||
|
window_size: int = ...,
|
||||||
|
) -> Iterator[_T | _U]: ...
|
||||||
|
def partitions(iterable: Iterable[_T]) -> Iterator[list[list[_T]]]: ...
|
||||||
|
def set_partitions(
|
||||||
|
iterable: Iterable[_T], k: int | None = ...
|
||||||
|
) -> Iterator[list[list[_T]]]: ...
|
||||||
|
|
||||||
|
class time_limited(Generic[_T], Iterator[_T]):
|
||||||
|
def __init__(
|
||||||
|
self, limit_seconds: float, iterable: Iterable[_T]
|
||||||
|
) -> None: ...
|
||||||
|
def __iter__(self) -> islice_extended[_T]: ...
|
||||||
|
def __next__(self) -> _T: ...
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def only(
|
||||||
|
iterable: Iterable[_T], *, too_long: _Raisable | None = ...
|
||||||
|
) -> _T | None: ...
|
||||||
|
@overload
|
||||||
|
def only(
|
||||||
|
iterable: Iterable[_T], default: _U, too_long: _Raisable | None = ...
|
||||||
|
) -> _T | _U: ...
|
||||||
|
def ichunked(iterable: Iterable[_T], n: int) -> Iterator[Iterator[_T]]: ...
|
||||||
|
def distinct_combinations(
|
||||||
|
iterable: Iterable[_T], r: int
|
||||||
|
) -> Iterator[tuple[_T, ...]]: ...
|
||||||
|
def filter_except(
|
||||||
|
validator: Callable[[Any], object],
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
*exceptions: Type[BaseException],
|
||||||
|
) -> Iterator[_T]: ...
|
||||||
|
def map_except(
|
||||||
|
function: Callable[[Any], _U],
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
*exceptions: Type[BaseException],
|
||||||
|
) -> Iterator[_U]: ...
|
||||||
|
def map_if(
|
||||||
|
iterable: Iterable[Any],
|
||||||
|
pred: Callable[[Any], bool],
|
||||||
|
func: Callable[[Any], Any],
|
||||||
|
func_else: Callable[[Any], Any] | None = ...,
|
||||||
|
) -> Iterator[Any]: ...
|
||||||
|
def sample(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
k: int,
|
||||||
|
weights: Iterable[float] | None = ...,
|
||||||
|
) -> list[_T]: ...
|
||||||
|
def is_sorted(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
key: Callable[[_T], _U] | None = ...,
|
||||||
|
reverse: bool = False,
|
||||||
|
strict: bool = False,
|
||||||
|
) -> bool: ...
|
||||||
|
|
||||||
|
class AbortThread(BaseException):
|
||||||
|
pass
|
||||||
|
|
||||||
|
class callback_iter(Generic[_T], Iterator[_T]):
|
||||||
|
def __init__(
|
||||||
|
self,
|
||||||
|
func: Callable[..., Any],
|
||||||
|
callback_kwd: str = ...,
|
||||||
|
wait_seconds: float = ...,
|
||||||
|
) -> None: ...
|
||||||
|
def __enter__(self) -> callback_iter[_T]: ...
|
||||||
|
def __exit__(
|
||||||
|
self,
|
||||||
|
exc_type: Type[BaseException] | None,
|
||||||
|
exc_value: BaseException | None,
|
||||||
|
traceback: TracebackType | None,
|
||||||
|
) -> bool | None: ...
|
||||||
|
def __iter__(self) -> callback_iter[_T]: ...
|
||||||
|
def __next__(self) -> _T: ...
|
||||||
|
def _reader(self) -> Iterator[_T]: ...
|
||||||
|
@property
|
||||||
|
def done(self) -> bool: ...
|
||||||
|
@property
|
||||||
|
def result(self) -> Any: ...
|
||||||
|
|
||||||
|
def windowed_complete(
|
||||||
|
iterable: Iterable[_T], n: int
|
||||||
|
) -> Iterator[tuple[_T, ...]]: ...
|
||||||
|
def all_unique(
|
||||||
|
iterable: Iterable[_T], key: Callable[[_T], _U] | None = ...
|
||||||
|
) -> bool: ...
|
||||||
|
def nth_product(index: int, *args: Iterable[_T]) -> tuple[_T, ...]: ...
|
||||||
|
def nth_combination_with_replacement(
|
||||||
|
iterable: Iterable[_T], r: int, index: int
|
||||||
|
) -> tuple[_T, ...]: ...
|
||||||
|
def nth_permutation(
|
||||||
|
iterable: Iterable[_T], r: int, index: int
|
||||||
|
) -> tuple[_T, ...]: ...
|
||||||
|
def value_chain(*args: _T | Iterable[_T]) -> Iterable[_T]: ...
|
||||||
|
def product_index(element: Iterable[_T], *args: Iterable[_T]) -> int: ...
|
||||||
|
def combination_index(
|
||||||
|
element: Iterable[_T], iterable: Iterable[_T]
|
||||||
|
) -> int: ...
|
||||||
|
def combination_with_replacement_index(
|
||||||
|
element: Iterable[_T], iterable: Iterable[_T]
|
||||||
|
) -> int: ...
|
||||||
|
def permutation_index(
|
||||||
|
element: Iterable[_T], iterable: Iterable[_T]
|
||||||
|
) -> int: ...
|
||||||
|
def repeat_each(iterable: Iterable[_T], n: int = ...) -> Iterator[_T]: ...
|
||||||
|
|
||||||
|
class countable(Generic[_T], Iterator[_T]):
|
||||||
|
def __init__(self, iterable: Iterable[_T]) -> None: ...
|
||||||
|
def __iter__(self) -> countable[_T]: ...
|
||||||
|
def __next__(self) -> _T: ...
|
||||||
|
|
||||||
|
def chunked_even(iterable: Iterable[_T], n: int) -> Iterator[list[_T]]: ...
|
||||||
|
def zip_broadcast(
|
||||||
|
*objects: _T | Iterable[_T],
|
||||||
|
scalar_types: type | tuple[type | tuple[Any, ...], ...] | None = ...,
|
||||||
|
strict: bool = ...,
|
||||||
|
) -> Iterable[tuple[_T, ...]]: ...
|
||||||
|
def unique_in_window(
|
||||||
|
iterable: Iterable[_T], n: int, key: Callable[[_T], _U] | None = ...
|
||||||
|
) -> Iterator[_T]: ...
|
||||||
|
def duplicates_everseen(
|
||||||
|
iterable: Iterable[_T], key: Callable[[_T], _U] | None = ...
|
||||||
|
) -> Iterator[_T]: ...
|
||||||
|
def duplicates_justseen(
|
||||||
|
iterable: Iterable[_T], key: Callable[[_T], _U] | None = ...
|
||||||
|
) -> Iterator[_T]: ...
|
||||||
|
def classify_unique(
|
||||||
|
iterable: Iterable[_T], key: Callable[[_T], _U] | None = ...
|
||||||
|
) -> Iterator[tuple[_T, bool, bool]]: ...
|
||||||
|
|
||||||
|
class _SupportsLessThan(Protocol):
|
||||||
|
def __lt__(self, __other: Any) -> bool: ...
|
||||||
|
|
||||||
|
_SupportsLessThanT = TypeVar("_SupportsLessThanT", bound=_SupportsLessThan)
|
||||||
|
|
||||||
|
@overload
|
||||||
|
def minmax(
|
||||||
|
iterable_or_value: Iterable[_SupportsLessThanT], *, key: None = None
|
||||||
|
) -> tuple[_SupportsLessThanT, _SupportsLessThanT]: ...
|
||||||
|
@overload
|
||||||
|
def minmax(
|
||||||
|
iterable_or_value: Iterable[_T], *, key: Callable[[_T], _SupportsLessThan]
|
||||||
|
) -> tuple[_T, _T]: ...
|
||||||
|
@overload
|
||||||
|
def minmax(
|
||||||
|
iterable_or_value: Iterable[_SupportsLessThanT],
|
||||||
|
*,
|
||||||
|
key: None = None,
|
||||||
|
default: _U,
|
||||||
|
) -> _U | tuple[_SupportsLessThanT, _SupportsLessThanT]: ...
|
||||||
|
@overload
|
||||||
|
def minmax(
|
||||||
|
iterable_or_value: Iterable[_T],
|
||||||
|
*,
|
||||||
|
key: Callable[[_T], _SupportsLessThan],
|
||||||
|
default: _U,
|
||||||
|
) -> _U | tuple[_T, _T]: ...
|
||||||
|
@overload
|
||||||
|
def minmax(
|
||||||
|
iterable_or_value: _SupportsLessThanT,
|
||||||
|
__other: _SupportsLessThanT,
|
||||||
|
*others: _SupportsLessThanT,
|
||||||
|
) -> tuple[_SupportsLessThanT, _SupportsLessThanT]: ...
|
||||||
|
@overload
|
||||||
|
def minmax(
|
||||||
|
iterable_or_value: _T,
|
||||||
|
__other: _T,
|
||||||
|
*others: _T,
|
||||||
|
key: Callable[[_T], _SupportsLessThan],
|
||||||
|
) -> tuple[_T, _T]: ...
|
||||||
|
def longest_common_prefix(
|
||||||
|
iterables: Iterable[Iterable[_T]],
|
||||||
|
) -> Iterator[_T]: ...
|
||||||
|
def iequals(*iterables: Iterable[Any]) -> bool: ...
|
||||||
|
def constrained_batches(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
max_size: int,
|
||||||
|
max_count: int | None = ...,
|
||||||
|
get_len: Callable[[_T], object] = ...,
|
||||||
|
strict: bool = ...,
|
||||||
|
) -> Iterator[tuple[_T]]: ...
|
||||||
|
def gray_product(*iterables: Iterable[_T]) -> Iterator[tuple[_T, ...]]: ...
|
||||||
|
def partial_product(*iterables: Iterable[_T]) -> Iterator[tuple[_T, ...]]: ...
|
||||||
|
def takewhile_inclusive(
|
||||||
|
predicate: Callable[[_T], bool], iterable: Iterable[_T]
|
||||||
|
) -> Iterator[_T]: ...
|
||||||
|
def outer_product(
|
||||||
|
func: Callable[[_T, _U], _V],
|
||||||
|
xs: Iterable[_T],
|
||||||
|
ys: Iterable[_U],
|
||||||
|
*args: Any,
|
||||||
|
**kwargs: Any,
|
||||||
|
) -> Iterator[tuple[_V, ...]]: ...
|
||||||
|
def iter_suppress(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
*exceptions: Type[BaseException],
|
||||||
|
) -> Iterator[_T]: ...
|
||||||
|
def filter_map(
|
||||||
|
func: Callable[[_T], _V | None],
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
) -> Iterator[_V]: ...
|
||||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,128 @@
|
||||||
|
"""Stubs for more_itertools.recipes"""
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from typing import (
|
||||||
|
Any,
|
||||||
|
Callable,
|
||||||
|
Iterable,
|
||||||
|
Iterator,
|
||||||
|
overload,
|
||||||
|
Sequence,
|
||||||
|
Type,
|
||||||
|
TypeVar,
|
||||||
|
)
|
||||||
|
|
||||||
|
# Type and type variable definitions
|
||||||
|
_T = TypeVar('_T')
|
||||||
|
_T1 = TypeVar('_T1')
|
||||||
|
_T2 = TypeVar('_T2')
|
||||||
|
_U = TypeVar('_U')
|
||||||
|
|
||||||
|
def take(n: int, iterable: Iterable[_T]) -> list[_T]: ...
|
||||||
|
def tabulate(
|
||||||
|
function: Callable[[int], _T], start: int = ...
|
||||||
|
) -> Iterator[_T]: ...
|
||||||
|
def tail(n: int, iterable: Iterable[_T]) -> Iterator[_T]: ...
|
||||||
|
def consume(iterator: Iterable[_T], n: int | None = ...) -> None: ...
|
||||||
|
@overload
|
||||||
|
def nth(iterable: Iterable[_T], n: int) -> _T | None: ...
|
||||||
|
@overload
|
||||||
|
def nth(iterable: Iterable[_T], n: int, default: _U) -> _T | _U: ...
|
||||||
|
def all_equal(iterable: Iterable[_T]) -> bool: ...
|
||||||
|
def quantify(
|
||||||
|
iterable: Iterable[_T], pred: Callable[[_T], bool] = ...
|
||||||
|
) -> int: ...
|
||||||
|
def pad_none(iterable: Iterable[_T]) -> Iterator[_T | None]: ...
|
||||||
|
def padnone(iterable: Iterable[_T]) -> Iterator[_T | None]: ...
|
||||||
|
def ncycles(iterable: Iterable[_T], n: int) -> Iterator[_T]: ...
|
||||||
|
def dotproduct(vec1: Iterable[_T1], vec2: Iterable[_T2]) -> Any: ...
|
||||||
|
def flatten(listOfLists: Iterable[Iterable[_T]]) -> Iterator[_T]: ...
|
||||||
|
def repeatfunc(
|
||||||
|
func: Callable[..., _U], times: int | None = ..., *args: Any
|
||||||
|
) -> Iterator[_U]: ...
|
||||||
|
def pairwise(iterable: Iterable[_T]) -> Iterator[tuple[_T, _T]]: ...
|
||||||
|
def grouper(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
n: int,
|
||||||
|
incomplete: str = ...,
|
||||||
|
fillvalue: _U = ...,
|
||||||
|
) -> Iterator[tuple[_T | _U, ...]]: ...
|
||||||
|
def roundrobin(*iterables: Iterable[_T]) -> Iterator[_T]: ...
|
||||||
|
def partition(
|
||||||
|
pred: Callable[[_T], object] | None, iterable: Iterable[_T]
|
||||||
|
) -> tuple[Iterator[_T], Iterator[_T]]: ...
|
||||||
|
def powerset(iterable: Iterable[_T]) -> Iterator[tuple[_T, ...]]: ...
|
||||||
|
def unique_everseen(
|
||||||
|
iterable: Iterable[_T], key: Callable[[_T], _U] | None = ...
|
||||||
|
) -> Iterator[_T]: ...
|
||||||
|
def unique_justseen(
|
||||||
|
iterable: Iterable[_T], key: Callable[[_T], object] | None = ...
|
||||||
|
) -> Iterator[_T]: ...
|
||||||
|
@overload
|
||||||
|
def iter_except(
|
||||||
|
func: Callable[[], _T],
|
||||||
|
exception: Type[BaseException] | tuple[Type[BaseException], ...],
|
||||||
|
first: None = ...,
|
||||||
|
) -> Iterator[_T]: ...
|
||||||
|
@overload
|
||||||
|
def iter_except(
|
||||||
|
func: Callable[[], _T],
|
||||||
|
exception: Type[BaseException] | tuple[Type[BaseException], ...],
|
||||||
|
first: Callable[[], _U],
|
||||||
|
) -> Iterator[_T | _U]: ...
|
||||||
|
@overload
|
||||||
|
def first_true(
|
||||||
|
iterable: Iterable[_T], *, pred: Callable[[_T], object] | None = ...
|
||||||
|
) -> _T | None: ...
|
||||||
|
@overload
|
||||||
|
def first_true(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
default: _U,
|
||||||
|
pred: Callable[[_T], object] | None = ...,
|
||||||
|
) -> _T | _U: ...
|
||||||
|
def random_product(
|
||||||
|
*args: Iterable[_T], repeat: int = ...
|
||||||
|
) -> tuple[_T, ...]: ...
|
||||||
|
def random_permutation(
|
||||||
|
iterable: Iterable[_T], r: int | None = ...
|
||||||
|
) -> tuple[_T, ...]: ...
|
||||||
|
def random_combination(iterable: Iterable[_T], r: int) -> tuple[_T, ...]: ...
|
||||||
|
def random_combination_with_replacement(
|
||||||
|
iterable: Iterable[_T], r: int
|
||||||
|
) -> tuple[_T, ...]: ...
|
||||||
|
def nth_combination(
|
||||||
|
iterable: Iterable[_T], r: int, index: int
|
||||||
|
) -> tuple[_T, ...]: ...
|
||||||
|
def prepend(value: _T, iterator: Iterable[_U]) -> Iterator[_T | _U]: ...
|
||||||
|
def convolve(signal: Iterable[_T], kernel: Iterable[_T]) -> Iterator[_T]: ...
|
||||||
|
def before_and_after(
|
||||||
|
predicate: Callable[[_T], bool], it: Iterable[_T]
|
||||||
|
) -> tuple[Iterator[_T], Iterator[_T]]: ...
|
||||||
|
def triplewise(iterable: Iterable[_T]) -> Iterator[tuple[_T, _T, _T]]: ...
|
||||||
|
def sliding_window(
|
||||||
|
iterable: Iterable[_T], n: int
|
||||||
|
) -> Iterator[tuple[_T, ...]]: ...
|
||||||
|
def subslices(iterable: Iterable[_T]) -> Iterator[list[_T]]: ...
|
||||||
|
def polynomial_from_roots(roots: Sequence[_T]) -> list[_T]: ...
|
||||||
|
def iter_index(
|
||||||
|
iterable: Iterable[_T],
|
||||||
|
value: Any,
|
||||||
|
start: int | None = ...,
|
||||||
|
stop: int | None = ...,
|
||||||
|
) -> Iterator[int]: ...
|
||||||
|
def sieve(n: int) -> Iterator[int]: ...
|
||||||
|
def batched(
|
||||||
|
iterable: Iterable[_T], n: int, *, strict: bool = False
|
||||||
|
) -> Iterator[tuple[_T]]: ...
|
||||||
|
def transpose(
|
||||||
|
it: Iterable[Iterable[_T]],
|
||||||
|
) -> Iterator[tuple[_T, ...]]: ...
|
||||||
|
def reshape(
|
||||||
|
matrix: Iterable[Iterable[_T]], cols: int
|
||||||
|
) -> Iterator[tuple[_T, ...]]: ...
|
||||||
|
def matmul(m1: Sequence[_T], m2: Sequence[_T]) -> Iterator[tuple[_T]]: ...
|
||||||
|
def factor(n: int) -> Iterator[int]: ...
|
||||||
|
def polynomial_eval(coefficients: Sequence[_T], x: _U) -> _U: ...
|
||||||
|
def sum_of_squares(it: Iterable[_T]) -> _T: ...
|
||||||
|
def polynomial_derivative(coefficients: Sequence[_T]) -> list[_T]: ...
|
||||||
|
def totient(n: int) -> int: ...
|
||||||
|
|
@ -0,0 +1,15 @@
|
||||||
|
# This file is dual licensed under the terms of the Apache License, Version
|
||||||
|
# 2.0, and the BSD License. See the LICENSE file in the root of this repository
|
||||||
|
# for complete details.
|
||||||
|
|
||||||
|
__title__ = "packaging"
|
||||||
|
__summary__ = "Core utilities for Python packages"
|
||||||
|
__uri__ = "https://github.com/pypa/packaging"
|
||||||
|
|
||||||
|
__version__ = "24.0"
|
||||||
|
|
||||||
|
__author__ = "Donald Stufft and individual contributors"
|
||||||
|
__email__ = "donald@stufft.io"
|
||||||
|
|
||||||
|
__license__ = "BSD-2-Clause or Apache-2.0"
|
||||||
|
__copyright__ = "2014 %s" % __author__
|
||||||
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
|
|
@ -0,0 +1,108 @@
|
||||||
|
"""
|
||||||
|
ELF file parser.
|
||||||
|
|
||||||
|
This provides a class ``ELFFile`` that parses an ELF executable in a similar
|
||||||
|
interface to ``ZipFile``. Only the read interface is implemented.
|
||||||
|
|
||||||
|
Based on: https://gist.github.com/lyssdod/f51579ae8d93c8657a5564aefc2ffbca
|
||||||
|
ELF header: https://refspecs.linuxfoundation.org/elf/gabi4+/ch4.eheader.html
|
||||||
|
"""
|
||||||
|
|
||||||
|
import enum
|
||||||
|
import os
|
||||||
|
import struct
|
||||||
|
from typing import IO, Optional, Tuple
|
||||||
|
|
||||||
|
|
||||||
|
class ELFInvalid(ValueError):
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
class EIClass(enum.IntEnum):
|
||||||
|
C32 = 1
|
||||||
|
C64 = 2
|
||||||
|
|
||||||
|
|
||||||
|
class EIData(enum.IntEnum):
|
||||||
|
Lsb = 1
|
||||||
|
Msb = 2
|
||||||
|
|
||||||
|
|
||||||
|
class EMachine(enum.IntEnum):
|
||||||
|
I386 = 3
|
||||||
|
S390 = 22
|
||||||
|
Arm = 40
|
||||||
|
X8664 = 62
|
||||||
|
AArc64 = 183
|
||||||
|
|
||||||
|
|
||||||
|
class ELFFile:
|
||||||
|
"""
|
||||||
|
Representation of an ELF executable.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(self, f: IO[bytes]) -> None:
|
||||||
|
self._f = f
|
||||||
|
|
||||||
|
try:
|
||||||
|
ident = self._read("16B")
|
||||||
|
except struct.error:
|
||||||
|
raise ELFInvalid("unable to parse identification")
|
||||||
|
magic = bytes(ident[:4])
|
||||||
|
if magic != b"\x7fELF":
|
||||||
|
raise ELFInvalid(f"invalid magic: {magic!r}")
|
||||||
|
|
||||||
|
self.capacity = ident[4] # Format for program header (bitness).
|
||||||
|
self.encoding = ident[5] # Data structure encoding (endianness).
|
||||||
|
|
||||||
|
try:
|
||||||
|
# e_fmt: Format for program header.
|
||||||
|
# p_fmt: Format for section header.
|
||||||
|
# p_idx: Indexes to find p_type, p_offset, and p_filesz.
|
||||||
|
e_fmt, self._p_fmt, self._p_idx = {
|
||||||
|
(1, 1): ("<HHIIIIIHHH", "<IIIIIIII", (0, 1, 4)), # 32-bit LSB.
|
||||||
|
(1, 2): (">HHIIIIIHHH", ">IIIIIIII", (0, 1, 4)), # 32-bit MSB.
|
||||||
|
(2, 1): ("<HHIQQQIHHH", "<IIQQQQQQ", (0, 2, 5)), # 64-bit LSB.
|
||||||
|
(2, 2): (">HHIQQQIHHH", ">IIQQQQQQ", (0, 2, 5)), # 64-bit MSB.
|
||||||
|
}[(self.capacity, self.encoding)]
|
||||||
|
except KeyError:
|
||||||
|
raise ELFInvalid(
|
||||||
|
f"unrecognized capacity ({self.capacity}) or "
|
||||||
|
f"encoding ({self.encoding})"
|
||||||
|
)
|
||||||
|
|
||||||
|
try:
|
||||||
|
(
|
||||||
|
_,
|
||||||
|
self.machine, # Architecture type.
|
||||||
|
_,
|
||||||
|
_,
|
||||||
|
self._e_phoff, # Offset of program header.
|
||||||
|
_,
|
||||||
|
self.flags, # Processor-specific flags.
|
||||||
|
_,
|
||||||
|
self._e_phentsize, # Size of section.
|
||||||
|
self._e_phnum, # Number of sections.
|
||||||
|
) = self._read(e_fmt)
|
||||||
|
except struct.error as e:
|
||||||
|
raise ELFInvalid("unable to parse machine and section information") from e
|
||||||
|
|
||||||
|
def _read(self, fmt: str) -> Tuple[int, ...]:
|
||||||
|
return struct.unpack(fmt, self._f.read(struct.calcsize(fmt)))
|
||||||
|
|
||||||
|
@property
|
||||||
|
def interpreter(self) -> Optional[str]:
|
||||||
|
"""
|
||||||
|
The path recorded in the ``PT_INTERP`` section header.
|
||||||
|
"""
|
||||||
|
for index in range(self._e_phnum):
|
||||||
|
self._f.seek(self._e_phoff + self._e_phentsize * index)
|
||||||
|
try:
|
||||||
|
data = self._read(self._p_fmt)
|
||||||
|
except struct.error:
|
||||||
|
continue
|
||||||
|
if data[self._p_idx[0]] != 3: # Not PT_INTERP.
|
||||||
|
continue
|
||||||
|
self._f.seek(data[self._p_idx[1]])
|
||||||
|
return os.fsdecode(self._f.read(data[self._p_idx[2]])).strip("\0")
|
||||||
|
return None
|
||||||
|
|
@ -0,0 +1,260 @@
|
||||||
|
import collections
|
||||||
|
import contextlib
|
||||||
|
import functools
|
||||||
|
import os
|
||||||
|
import re
|
||||||
|
import sys
|
||||||
|
import warnings
|
||||||
|
from typing import Dict, Generator, Iterator, NamedTuple, Optional, Sequence, Tuple
|
||||||
|
|
||||||
|
from ._elffile import EIClass, EIData, ELFFile, EMachine
|
||||||
|
|
||||||
|
EF_ARM_ABIMASK = 0xFF000000
|
||||||
|
EF_ARM_ABI_VER5 = 0x05000000
|
||||||
|
EF_ARM_ABI_FLOAT_HARD = 0x00000400
|
||||||
|
|
||||||
|
|
||||||
|
# `os.PathLike` not a generic type until Python 3.9, so sticking with `str`
|
||||||
|
# as the type for `path` until then.
|
||||||
|
@contextlib.contextmanager
|
||||||
|
def _parse_elf(path: str) -> Generator[Optional[ELFFile], None, None]:
|
||||||
|
try:
|
||||||
|
with open(path, "rb") as f:
|
||||||
|
yield ELFFile(f)
|
||||||
|
except (OSError, TypeError, ValueError):
|
||||||
|
yield None
|
||||||
|
|
||||||
|
|
||||||
|
def _is_linux_armhf(executable: str) -> bool:
|
||||||
|
# hard-float ABI can be detected from the ELF header of the running
|
||||||
|
# process
|
||||||
|
# https://static.docs.arm.com/ihi0044/g/aaelf32.pdf
|
||||||
|
with _parse_elf(executable) as f:
|
||||||
|
return (
|
||||||
|
f is not None
|
||||||
|
and f.capacity == EIClass.C32
|
||||||
|
and f.encoding == EIData.Lsb
|
||||||
|
and f.machine == EMachine.Arm
|
||||||
|
and f.flags & EF_ARM_ABIMASK == EF_ARM_ABI_VER5
|
||||||
|
and f.flags & EF_ARM_ABI_FLOAT_HARD == EF_ARM_ABI_FLOAT_HARD
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def _is_linux_i686(executable: str) -> bool:
|
||||||
|
with _parse_elf(executable) as f:
|
||||||
|
return (
|
||||||
|
f is not None
|
||||||
|
and f.capacity == EIClass.C32
|
||||||
|
and f.encoding == EIData.Lsb
|
||||||
|
and f.machine == EMachine.I386
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def _have_compatible_abi(executable: str, archs: Sequence[str]) -> bool:
|
||||||
|
if "armv7l" in archs:
|
||||||
|
return _is_linux_armhf(executable)
|
||||||
|
if "i686" in archs:
|
||||||
|
return _is_linux_i686(executable)
|
||||||
|
allowed_archs = {
|
||||||
|
"x86_64",
|
||||||
|
"aarch64",
|
||||||
|
"ppc64",
|
||||||
|
"ppc64le",
|
||||||
|
"s390x",
|
||||||
|
"loongarch64",
|
||||||
|
"riscv64",
|
||||||
|
}
|
||||||
|
return any(arch in allowed_archs for arch in archs)
|
||||||
|
|
||||||
|
|
||||||
|
# If glibc ever changes its major version, we need to know what the last
|
||||||
|
# minor version was, so we can build the complete list of all versions.
|
||||||
|
# For now, guess what the highest minor version might be, assume it will
|
||||||
|
# be 50 for testing. Once this actually happens, update the dictionary
|
||||||
|
# with the actual value.
|
||||||
|
_LAST_GLIBC_MINOR: Dict[int, int] = collections.defaultdict(lambda: 50)
|
||||||
|
|
||||||
|
|
||||||
|
class _GLibCVersion(NamedTuple):
|
||||||
|
major: int
|
||||||
|
minor: int
|
||||||
|
|
||||||
|
|
||||||
|
def _glibc_version_string_confstr() -> Optional[str]:
|
||||||
|
"""
|
||||||
|
Primary implementation of glibc_version_string using os.confstr.
|
||||||
|
"""
|
||||||
|
# os.confstr is quite a bit faster than ctypes.DLL. It's also less likely
|
||||||
|
# to be broken or missing. This strategy is used in the standard library
|
||||||
|
# platform module.
|
||||||
|
# https://github.com/python/cpython/blob/fcf1d003bf4f0100c/Lib/platform.py#L175-L183
|
||||||
|
try:
|
||||||
|
# Should be a string like "glibc 2.17".
|
||||||
|
version_string: Optional[str] = os.confstr("CS_GNU_LIBC_VERSION")
|
||||||
|
assert version_string is not None
|
||||||
|
_, version = version_string.rsplit()
|
||||||
|
except (AssertionError, AttributeError, OSError, ValueError):
|
||||||
|
# os.confstr() or CS_GNU_LIBC_VERSION not available (or a bad value)...
|
||||||
|
return None
|
||||||
|
return version
|
||||||
|
|
||||||
|
|
||||||
|
def _glibc_version_string_ctypes() -> Optional[str]:
|
||||||
|
"""
|
||||||
|
Fallback implementation of glibc_version_string using ctypes.
|
||||||
|
"""
|
||||||
|
try:
|
||||||
|
import ctypes
|
||||||
|
except ImportError:
|
||||||
|
return None
|
||||||
|
|
||||||
|
# ctypes.CDLL(None) internally calls dlopen(NULL), and as the dlopen
|
||||||
|
# manpage says, "If filename is NULL, then the returned handle is for the
|
||||||
|
# main program". This way we can let the linker do the work to figure out
|
||||||
|
# which libc our process is actually using.
|
||||||
|
#
|
||||||
|
# We must also handle the special case where the executable is not a
|
||||||
|
# dynamically linked executable. This can occur when using musl libc,
|
||||||
|
# for example. In this situation, dlopen() will error, leading to an
|
||||||
|
# OSError. Interestingly, at least in the case of musl, there is no
|
||||||
|
# errno set on the OSError. The single string argument used to construct
|
||||||
|
# OSError comes from libc itself and is therefore not portable to
|
||||||
|
# hard code here. In any case, failure to call dlopen() means we
|
||||||
|
# can proceed, so we bail on our attempt.
|
||||||
|
try:
|
||||||
|
process_namespace = ctypes.CDLL(None)
|
||||||
|
except OSError:
|
||||||
|
return None
|
||||||
|
|
||||||
|
try:
|
||||||
|
gnu_get_libc_version = process_namespace.gnu_get_libc_version
|
||||||
|
except AttributeError:
|
||||||
|
# Symbol doesn't exist -> therefore, we are not linked to
|
||||||
|
# glibc.
|
||||||
|
return None
|
||||||
|
|
||||||
|
# Call gnu_get_libc_version, which returns a string like "2.5"
|
||||||
|
gnu_get_libc_version.restype = ctypes.c_char_p
|
||||||
|
version_str: str = gnu_get_libc_version()
|
||||||
|
# py2 / py3 compatibility:
|
||||||
|
if not isinstance(version_str, str):
|
||||||
|
version_str = version_str.decode("ascii")
|
||||||
|
|
||||||
|
return version_str
|
||||||
|
|
||||||
|
|
||||||
|
def _glibc_version_string() -> Optional[str]:
|
||||||
|
"""Returns glibc version string, or None if not using glibc."""
|
||||||
|
return _glibc_version_string_confstr() or _glibc_version_string_ctypes()
|
||||||
|
|
||||||
|
|
||||||
|
def _parse_glibc_version(version_str: str) -> Tuple[int, int]:
|
||||||
|
"""Parse glibc version.
|
||||||
|
|
||||||
|
We use a regexp instead of str.split because we want to discard any
|
||||||
|
random junk that might come after the minor version -- this might happen
|
||||||
|
in patched/forked versions of glibc (e.g. Linaro's version of glibc
|
||||||
|
uses version strings like "2.20-2014.11"). See gh-3588.
|
||||||
|
"""
|
||||||
|
m = re.match(r"(?P<major>[0-9]+)\.(?P<minor>[0-9]+)", version_str)
|
||||||
|
if not m:
|
||||||
|
warnings.warn(
|
||||||
|
f"Expected glibc version with 2 components major.minor,"
|
||||||
|
f" got: {version_str}",
|
||||||
|
RuntimeWarning,
|
||||||
|
)
|
||||||
|
return -1, -1
|
||||||
|
return int(m.group("major")), int(m.group("minor"))
|
||||||
|
|
||||||
|
|
||||||
|
@functools.lru_cache()
|
||||||
|
def _get_glibc_version() -> Tuple[int, int]:
|
||||||
|
version_str = _glibc_version_string()
|
||||||
|
if version_str is None:
|
||||||
|
return (-1, -1)
|
||||||
|
return _parse_glibc_version(version_str)
|
||||||
|
|
||||||
|
|
||||||
|
# From PEP 513, PEP 600
|
||||||
|
def _is_compatible(arch: str, version: _GLibCVersion) -> bool:
|
||||||
|
sys_glibc = _get_glibc_version()
|
||||||
|
if sys_glibc < version:
|
||||||
|
return False
|
||||||
|
# Check for presence of _manylinux module.
|
||||||
|
try:
|
||||||
|
import _manylinux
|
||||||
|
except ImportError:
|
||||||
|
return True
|
||||||
|
if hasattr(_manylinux, "manylinux_compatible"):
|
||||||
|
result = _manylinux.manylinux_compatible(version[0], version[1], arch)
|
||||||
|
if result is not None:
|
||||||
|
return bool(result)
|
||||||
|
return True
|
||||||
|
if version == _GLibCVersion(2, 5):
|
||||||
|
if hasattr(_manylinux, "manylinux1_compatible"):
|
||||||
|
return bool(_manylinux.manylinux1_compatible)
|
||||||
|
if version == _GLibCVersion(2, 12):
|
||||||
|
if hasattr(_manylinux, "manylinux2010_compatible"):
|
||||||
|
return bool(_manylinux.manylinux2010_compatible)
|
||||||
|
if version == _GLibCVersion(2, 17):
|
||||||
|
if hasattr(_manylinux, "manylinux2014_compatible"):
|
||||||
|
return bool(_manylinux.manylinux2014_compatible)
|
||||||
|
return True
|
||||||
|
|
||||||
|
|
||||||
|
_LEGACY_MANYLINUX_MAP = {
|
||||||
|
# CentOS 7 w/ glibc 2.17 (PEP 599)
|
||||||
|
(2, 17): "manylinux2014",
|
||||||
|
# CentOS 6 w/ glibc 2.12 (PEP 571)
|
||||||
|
(2, 12): "manylinux2010",
|
||||||
|
# CentOS 5 w/ glibc 2.5 (PEP 513)
|
||||||
|
(2, 5): "manylinux1",
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
def platform_tags(archs: Sequence[str]) -> Iterator[str]:
|
||||||
|
"""Generate manylinux tags compatible to the current platform.
|
||||||
|
|
||||||
|
:param archs: Sequence of compatible architectures.
|
||||||
|
The first one shall be the closest to the actual architecture and be the part of
|
||||||
|
platform tag after the ``linux_`` prefix, e.g. ``x86_64``.
|
||||||
|
The ``linux_`` prefix is assumed as a prerequisite for the current platform to
|
||||||
|
be manylinux-compatible.
|
||||||
|
|
||||||
|
:returns: An iterator of compatible manylinux tags.
|
||||||
|
"""
|
||||||
|
if not _have_compatible_abi(sys.executable, archs):
|
||||||
|
return
|
||||||
|
# Oldest glibc to be supported regardless of architecture is (2, 17).
|
||||||
|
too_old_glibc2 = _GLibCVersion(2, 16)
|
||||||
|
if set(archs) & {"x86_64", "i686"}:
|
||||||
|
# On x86/i686 also oldest glibc to be supported is (2, 5).
|
||||||
|
too_old_glibc2 = _GLibCVersion(2, 4)
|
||||||
|
current_glibc = _GLibCVersion(*_get_glibc_version())
|
||||||
|
glibc_max_list = [current_glibc]
|
||||||
|
# We can assume compatibility across glibc major versions.
|
||||||
|
# https://sourceware.org/bugzilla/show_bug.cgi?id=24636
|
||||||
|
#
|
||||||
|
# Build a list of maximum glibc versions so that we can
|
||||||
|
# output the canonical list of all glibc from current_glibc
|
||||||
|
# down to too_old_glibc2, including all intermediary versions.
|
||||||
|
for glibc_major in range(current_glibc.major - 1, 1, -1):
|
||||||
|
glibc_minor = _LAST_GLIBC_MINOR[glibc_major]
|
||||||
|
glibc_max_list.append(_GLibCVersion(glibc_major, glibc_minor))
|
||||||
|
for arch in archs:
|
||||||
|
for glibc_max in glibc_max_list:
|
||||||
|
if glibc_max.major == too_old_glibc2.major:
|
||||||
|
min_minor = too_old_glibc2.minor
|
||||||
|
else:
|
||||||
|
# For other glibc major versions oldest supported is (x, 0).
|
||||||
|
min_minor = -1
|
||||||
|
for glibc_minor in range(glibc_max.minor, min_minor, -1):
|
||||||
|
glibc_version = _GLibCVersion(glibc_max.major, glibc_minor)
|
||||||
|
tag = "manylinux_{}_{}".format(*glibc_version)
|
||||||
|
if _is_compatible(arch, glibc_version):
|
||||||
|
yield f"{tag}_{arch}"
|
||||||
|
# Handle the legacy manylinux1, manylinux2010, manylinux2014 tags.
|
||||||
|
if glibc_version in _LEGACY_MANYLINUX_MAP:
|
||||||
|
legacy_tag = _LEGACY_MANYLINUX_MAP[glibc_version]
|
||||||
|
if _is_compatible(arch, glibc_version):
|
||||||
|
yield f"{legacy_tag}_{arch}"
|
||||||
|
|
@ -0,0 +1,83 @@
|
||||||
|
"""PEP 656 support.
|
||||||
|
|
||||||
|
This module implements logic to detect if the currently running Python is
|
||||||
|
linked against musl, and what musl version is used.
|
||||||
|
"""
|
||||||
|
|
||||||
|
import functools
|
||||||
|
import re
|
||||||
|
import subprocess
|
||||||
|
import sys
|
||||||
|
from typing import Iterator, NamedTuple, Optional, Sequence
|
||||||
|
|
||||||
|
from ._elffile import ELFFile
|
||||||
|
|
||||||
|
|
||||||
|
class _MuslVersion(NamedTuple):
|
||||||
|
major: int
|
||||||
|
minor: int
|
||||||
|
|
||||||
|
|
||||||
|
def _parse_musl_version(output: str) -> Optional[_MuslVersion]:
|
||||||
|
lines = [n for n in (n.strip() for n in output.splitlines()) if n]
|
||||||
|
if len(lines) < 2 or lines[0][:4] != "musl":
|
||||||
|
return None
|
||||||
|
m = re.match(r"Version (\d+)\.(\d+)", lines[1])
|
||||||
|
if not m:
|
||||||
|
return None
|
||||||
|
return _MuslVersion(major=int(m.group(1)), minor=int(m.group(2)))
|
||||||
|
|
||||||
|
|
||||||
|
@functools.lru_cache()
|
||||||
|
def _get_musl_version(executable: str) -> Optional[_MuslVersion]:
|
||||||
|
"""Detect currently-running musl runtime version.
|
||||||
|
|
||||||
|
This is done by checking the specified executable's dynamic linking
|
||||||
|
information, and invoking the loader to parse its output for a version
|
||||||
|
string. If the loader is musl, the output would be something like::
|
||||||
|
|
||||||
|
musl libc (x86_64)
|
||||||
|
Version 1.2.2
|
||||||
|
Dynamic Program Loader
|
||||||
|
"""
|
||||||
|
try:
|
||||||
|
with open(executable, "rb") as f:
|
||||||
|
ld = ELFFile(f).interpreter
|
||||||
|
except (OSError, TypeError, ValueError):
|
||||||
|
return None
|
||||||
|
if ld is None or "musl" not in ld:
|
||||||
|
return None
|
||||||
|
proc = subprocess.run([ld], stderr=subprocess.PIPE, text=True)
|
||||||
|
return _parse_musl_version(proc.stderr)
|
||||||
|
|
||||||
|
|
||||||
|
def platform_tags(archs: Sequence[str]) -> Iterator[str]:
|
||||||
|
"""Generate musllinux tags compatible to the current platform.
|
||||||
|
|
||||||
|
:param archs: Sequence of compatible architectures.
|
||||||
|
The first one shall be the closest to the actual architecture and be the part of
|
||||||
|
platform tag after the ``linux_`` prefix, e.g. ``x86_64``.
|
||||||
|
The ``linux_`` prefix is assumed as a prerequisite for the current platform to
|
||||||
|
be musllinux-compatible.
|
||||||
|
|
||||||
|
:returns: An iterator of compatible musllinux tags.
|
||||||
|
"""
|
||||||
|
sys_musl = _get_musl_version(sys.executable)
|
||||||
|
if sys_musl is None: # Python not dynamically linked against musl.
|
||||||
|
return
|
||||||
|
for arch in archs:
|
||||||
|
for minor in range(sys_musl.minor, -1, -1):
|
||||||
|
yield f"musllinux_{sys_musl.major}_{minor}_{arch}"
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__": # pragma: no cover
|
||||||
|
import sysconfig
|
||||||
|
|
||||||
|
plat = sysconfig.get_platform()
|
||||||
|
assert plat.startswith("linux-"), "not linux"
|
||||||
|
|
||||||
|
print("plat:", plat)
|
||||||
|
print("musl:", _get_musl_version(sys.executable))
|
||||||
|
print("tags:", end=" ")
|
||||||
|
for t in platform_tags(re.sub(r"[.-]", "_", plat.split("-", 1)[-1])):
|
||||||
|
print(t, end="\n ")
|
||||||
|
|
@ -0,0 +1,356 @@
|
||||||
|
"""Handwritten parser of dependency specifiers.
|
||||||
|
|
||||||
|
The docstring for each __parse_* function contains ENBF-inspired grammar representing
|
||||||
|
the implementation.
|
||||||
|
"""
|
||||||
|
|
||||||
|
import ast
|
||||||
|
from typing import Any, List, NamedTuple, Optional, Tuple, Union
|
||||||
|
|
||||||
|
from ._tokenizer import DEFAULT_RULES, Tokenizer
|
||||||
|
|
||||||
|
|
||||||
|
class Node:
|
||||||
|
def __init__(self, value: str) -> None:
|
||||||
|
self.value = value
|
||||||
|
|
||||||
|
def __str__(self) -> str:
|
||||||
|
return self.value
|
||||||
|
|
||||||
|
def __repr__(self) -> str:
|
||||||
|
return f"<{self.__class__.__name__}('{self}')>"
|
||||||
|
|
||||||
|
def serialize(self) -> str:
|
||||||
|
raise NotImplementedError
|
||||||
|
|
||||||
|
|
||||||
|
class Variable(Node):
|
||||||
|
def serialize(self) -> str:
|
||||||
|
return str(self)
|
||||||
|
|
||||||
|
|
||||||
|
class Value(Node):
|
||||||
|
def serialize(self) -> str:
|
||||||
|
return f'"{self}"'
|
||||||
|
|
||||||
|
|
||||||
|
class Op(Node):
|
||||||
|
def serialize(self) -> str:
|
||||||
|
return str(self)
|
||||||
|
|
||||||
|
|
||||||
|
MarkerVar = Union[Variable, Value]
|
||||||
|
MarkerItem = Tuple[MarkerVar, Op, MarkerVar]
|
||||||
|
# MarkerAtom = Union[MarkerItem, List["MarkerAtom"]]
|
||||||
|
# MarkerList = List[Union["MarkerList", MarkerAtom, str]]
|
||||||
|
# mypy does not support recursive type definition
|
||||||
|
# https://github.com/python/mypy/issues/731
|
||||||
|
MarkerAtom = Any
|
||||||
|
MarkerList = List[Any]
|
||||||
|
|
||||||
|
|
||||||
|
class ParsedRequirement(NamedTuple):
|
||||||
|
name: str
|
||||||
|
url: str
|
||||||
|
extras: List[str]
|
||||||
|
specifier: str
|
||||||
|
marker: Optional[MarkerList]
|
||||||
|
|
||||||
|
|
||||||
|
# --------------------------------------------------------------------------------------
|
||||||
|
# Recursive descent parser for dependency specifier
|
||||||
|
# --------------------------------------------------------------------------------------
|
||||||
|
def parse_requirement(source: str) -> ParsedRequirement:
|
||||||
|
return _parse_requirement(Tokenizer(source, rules=DEFAULT_RULES))
|
||||||
|
|
||||||
|
|
||||||
|
def _parse_requirement(tokenizer: Tokenizer) -> ParsedRequirement:
|
||||||
|
"""
|
||||||
|
requirement = WS? IDENTIFIER WS? extras WS? requirement_details
|
||||||
|
"""
|
||||||
|
tokenizer.consume("WS")
|
||||||
|
|
||||||
|
name_token = tokenizer.expect(
|
||||||
|
"IDENTIFIER", expected="package name at the start of dependency specifier"
|
||||||
|
)
|
||||||
|
name = name_token.text
|
||||||
|
tokenizer.consume("WS")
|
||||||
|
|
||||||
|
extras = _parse_extras(tokenizer)
|
||||||
|
tokenizer.consume("WS")
|
||||||
|
|
||||||
|
url, specifier, marker = _parse_requirement_details(tokenizer)
|
||||||
|
tokenizer.expect("END", expected="end of dependency specifier")
|
||||||
|
|
||||||
|
return ParsedRequirement(name, url, extras, specifier, marker)
|
||||||
|
|
||||||
|
|
||||||
|
def _parse_requirement_details(
|
||||||
|
tokenizer: Tokenizer,
|
||||||
|
) -> Tuple[str, str, Optional[MarkerList]]:
|
||||||
|
"""
|
||||||
|
requirement_details = AT URL (WS requirement_marker?)?
|
||||||
|
| specifier WS? (requirement_marker)?
|
||||||
|
"""
|
||||||
|
|
||||||
|
specifier = ""
|
||||||
|
url = ""
|
||||||
|
marker = None
|
||||||
|
|
||||||
|
if tokenizer.check("AT"):
|
||||||
|
tokenizer.read()
|
||||||
|
tokenizer.consume("WS")
|
||||||
|
|
||||||
|
url_start = tokenizer.position
|
||||||
|
url = tokenizer.expect("URL", expected="URL after @").text
|
||||||
|
if tokenizer.check("END", peek=True):
|
||||||
|
return (url, specifier, marker)
|
||||||
|
|
||||||
|
tokenizer.expect("WS", expected="whitespace after URL")
|
||||||
|
|
||||||
|
# The input might end after whitespace.
|
||||||
|
if tokenizer.check("END", peek=True):
|
||||||
|
return (url, specifier, marker)
|
||||||
|
|
||||||
|
marker = _parse_requirement_marker(
|
||||||
|
tokenizer, span_start=url_start, after="URL and whitespace"
|
||||||
|
)
|
||||||
|
else:
|
||||||
|
specifier_start = tokenizer.position
|
||||||
|
specifier = _parse_specifier(tokenizer)
|
||||||
|
tokenizer.consume("WS")
|
||||||
|
|
||||||
|
if tokenizer.check("END", peek=True):
|
||||||
|
return (url, specifier, marker)
|
||||||
|
|
||||||
|
marker = _parse_requirement_marker(
|
||||||
|
tokenizer,
|
||||||
|
span_start=specifier_start,
|
||||||
|
after=(
|
||||||
|
"version specifier"
|
||||||
|
if specifier
|
||||||
|
else "name and no valid version specifier"
|
||||||
|
),
|
||||||
|
)
|
||||||
|
|
||||||
|
return (url, specifier, marker)
|
||||||
|
|
||||||
|
|
||||||
|
def _parse_requirement_marker(
|
||||||
|
tokenizer: Tokenizer, *, span_start: int, after: str
|
||||||
|
) -> MarkerList:
|
||||||
|
"""
|
||||||
|
requirement_marker = SEMICOLON marker WS?
|
||||||
|
"""
|
||||||
|
|
||||||
|
if not tokenizer.check("SEMICOLON"):
|
||||||
|
tokenizer.raise_syntax_error(
|
||||||
|
f"Expected end or semicolon (after {after})",
|
||||||
|
span_start=span_start,
|
||||||
|
)
|
||||||
|
tokenizer.read()
|
||||||
|
|
||||||
|
marker = _parse_marker(tokenizer)
|
||||||
|
tokenizer.consume("WS")
|
||||||
|
|
||||||
|
return marker
|
||||||
|
|
||||||
|
|
||||||
|
def _parse_extras(tokenizer: Tokenizer) -> List[str]:
|
||||||
|
"""
|
||||||
|
extras = (LEFT_BRACKET wsp* extras_list? wsp* RIGHT_BRACKET)?
|
||||||
|
"""
|
||||||
|
if not tokenizer.check("LEFT_BRACKET", peek=True):
|
||||||
|
return []
|
||||||
|
|
||||||
|
with tokenizer.enclosing_tokens(
|
||||||
|
"LEFT_BRACKET",
|
||||||
|
"RIGHT_BRACKET",
|
||||||
|
around="extras",
|
||||||
|
):
|
||||||
|
tokenizer.consume("WS")
|
||||||
|
extras = _parse_extras_list(tokenizer)
|
||||||
|
tokenizer.consume("WS")
|
||||||
|
|
||||||
|
return extras
|
||||||
|
|
||||||
|
|
||||||
|
def _parse_extras_list(tokenizer: Tokenizer) -> List[str]:
|
||||||
|
"""
|
||||||
|
extras_list = identifier (wsp* ',' wsp* identifier)*
|
||||||
|
"""
|
||||||
|
extras: List[str] = []
|
||||||
|
|
||||||
|
if not tokenizer.check("IDENTIFIER"):
|
||||||
|
return extras
|
||||||
|
|
||||||
|
extras.append(tokenizer.read().text)
|
||||||
|
|
||||||
|
while True:
|
||||||
|
tokenizer.consume("WS")
|
||||||
|
if tokenizer.check("IDENTIFIER", peek=True):
|
||||||
|
tokenizer.raise_syntax_error("Expected comma between extra names")
|
||||||
|
elif not tokenizer.check("COMMA"):
|
||||||
|
break
|
||||||
|
|
||||||
|
tokenizer.read()
|
||||||
|
tokenizer.consume("WS")
|
||||||
|
|
||||||
|
extra_token = tokenizer.expect("IDENTIFIER", expected="extra name after comma")
|
||||||
|
extras.append(extra_token.text)
|
||||||
|
|
||||||
|
return extras
|
||||||
|
|
||||||
|
|
||||||
|
def _parse_specifier(tokenizer: Tokenizer) -> str:
|
||||||
|
"""
|
||||||
|
specifier = LEFT_PARENTHESIS WS? version_many WS? RIGHT_PARENTHESIS
|
||||||
|
| WS? version_many WS?
|
||||||
|
"""
|
||||||
|
with tokenizer.enclosing_tokens(
|
||||||
|
"LEFT_PARENTHESIS",
|
||||||
|
"RIGHT_PARENTHESIS",
|
||||||
|
around="version specifier",
|
||||||
|
):
|
||||||
|
tokenizer.consume("WS")
|
||||||
|
parsed_specifiers = _parse_version_many(tokenizer)
|
||||||
|
tokenizer.consume("WS")
|
||||||
|
|
||||||
|
return parsed_specifiers
|
||||||
|
|
||||||
|
|
||||||
|
def _parse_version_many(tokenizer: Tokenizer) -> str:
|
||||||
|
"""
|
||||||
|
version_many = (SPECIFIER (WS? COMMA WS? SPECIFIER)*)?
|
||||||
|
"""
|
||||||
|
parsed_specifiers = ""
|
||||||
|
while tokenizer.check("SPECIFIER"):
|
||||||
|
span_start = tokenizer.position
|
||||||
|
parsed_specifiers += tokenizer.read().text
|
||||||
|
if tokenizer.check("VERSION_PREFIX_TRAIL", peek=True):
|
||||||
|
tokenizer.raise_syntax_error(
|
||||||
|
".* suffix can only be used with `==` or `!=` operators",
|
||||||
|
span_start=span_start,
|
||||||
|
span_end=tokenizer.position + 1,
|
||||||
|
)
|
||||||
|
if tokenizer.check("VERSION_LOCAL_LABEL_TRAIL", peek=True):
|
||||||
|
tokenizer.raise_syntax_error(
|
||||||
|
"Local version label can only be used with `==` or `!=` operators",
|
||||||
|
span_start=span_start,
|
||||||
|
span_end=tokenizer.position,
|
||||||
|
)
|
||||||
|
tokenizer.consume("WS")
|
||||||
|
if not tokenizer.check("COMMA"):
|
||||||
|
break
|
||||||
|
parsed_specifiers += tokenizer.read().text
|
||||||
|
tokenizer.consume("WS")
|
||||||
|
|
||||||
|
return parsed_specifiers
|
||||||
|
|
||||||
|
|
||||||
|
# --------------------------------------------------------------------------------------
|
||||||
|
# Recursive descent parser for marker expression
|
||||||
|
# --------------------------------------------------------------------------------------
|
||||||
|
def parse_marker(source: str) -> MarkerList:
|
||||||
|
return _parse_full_marker(Tokenizer(source, rules=DEFAULT_RULES))
|
||||||
|
|
||||||
|
|
||||||
|
def _parse_full_marker(tokenizer: Tokenizer) -> MarkerList:
|
||||||
|
retval = _parse_marker(tokenizer)
|
||||||
|
tokenizer.expect("END", expected="end of marker expression")
|
||||||
|
return retval
|
||||||
|
|
||||||
|
|
||||||
|
def _parse_marker(tokenizer: Tokenizer) -> MarkerList:
|
||||||
|
"""
|
||||||
|
marker = marker_atom (BOOLOP marker_atom)+
|
||||||
|
"""
|
||||||
|
expression = [_parse_marker_atom(tokenizer)]
|
||||||
|
while tokenizer.check("BOOLOP"):
|
||||||
|
token = tokenizer.read()
|
||||||
|
expr_right = _parse_marker_atom(tokenizer)
|
||||||
|
expression.extend((token.text, expr_right))
|
||||||
|
return expression
|
||||||
|
|
||||||
|
|
||||||
|
def _parse_marker_atom(tokenizer: Tokenizer) -> MarkerAtom:
|
||||||
|
"""
|
||||||
|
marker_atom = WS? LEFT_PARENTHESIS WS? marker WS? RIGHT_PARENTHESIS WS?
|
||||||
|
| WS? marker_item WS?
|
||||||
|
"""
|
||||||
|
|
||||||
|
tokenizer.consume("WS")
|
||||||
|
if tokenizer.check("LEFT_PARENTHESIS", peek=True):
|
||||||
|
with tokenizer.enclosing_tokens(
|
||||||
|
"LEFT_PARENTHESIS",
|
||||||
|
"RIGHT_PARENTHESIS",
|
||||||
|
around="marker expression",
|
||||||
|
):
|
||||||
|
tokenizer.consume("WS")
|
||||||
|
marker: MarkerAtom = _parse_marker(tokenizer)
|
||||||
|
tokenizer.consume("WS")
|
||||||
|
else:
|
||||||
|
marker = _parse_marker_item(tokenizer)
|
||||||
|
tokenizer.consume("WS")
|
||||||
|
return marker
|
||||||
|
|
||||||
|
|
||||||
|
def _parse_marker_item(tokenizer: Tokenizer) -> MarkerItem:
|
||||||
|
"""
|
||||||
|
marker_item = WS? marker_var WS? marker_op WS? marker_var WS?
|
||||||
|
"""
|
||||||
|
tokenizer.consume("WS")
|
||||||
|
marker_var_left = _parse_marker_var(tokenizer)
|
||||||
|
tokenizer.consume("WS")
|
||||||
|
marker_op = _parse_marker_op(tokenizer)
|
||||||
|
tokenizer.consume("WS")
|
||||||
|
marker_var_right = _parse_marker_var(tokenizer)
|
||||||
|
tokenizer.consume("WS")
|
||||||
|
return (marker_var_left, marker_op, marker_var_right)
|
||||||
|
|
||||||
|
|
||||||
|
def _parse_marker_var(tokenizer: Tokenizer) -> MarkerVar:
|
||||||
|
"""
|
||||||
|
marker_var = VARIABLE | QUOTED_STRING
|
||||||
|
"""
|
||||||
|
if tokenizer.check("VARIABLE"):
|
||||||
|
return process_env_var(tokenizer.read().text.replace(".", "_"))
|
||||||
|
elif tokenizer.check("QUOTED_STRING"):
|
||||||
|
return process_python_str(tokenizer.read().text)
|
||||||
|
else:
|
||||||
|
tokenizer.raise_syntax_error(
|
||||||
|
message="Expected a marker variable or quoted string"
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def process_env_var(env_var: str) -> Variable:
|
||||||
|
if env_var in ("platform_python_implementation", "python_implementation"):
|
||||||
|
return Variable("platform_python_implementation")
|
||||||
|
else:
|
||||||
|
return Variable(env_var)
|
||||||
|
|
||||||
|
|
||||||
|
def process_python_str(python_str: str) -> Value:
|
||||||
|
value = ast.literal_eval(python_str)
|
||||||
|
return Value(str(value))
|
||||||
|
|
||||||
|
|
||||||
|
def _parse_marker_op(tokenizer: Tokenizer) -> Op:
|
||||||
|
"""
|
||||||
|
marker_op = IN | NOT IN | OP
|
||||||
|
"""
|
||||||
|
if tokenizer.check("IN"):
|
||||||
|
tokenizer.read()
|
||||||
|
return Op("in")
|
||||||
|
elif tokenizer.check("NOT"):
|
||||||
|
tokenizer.read()
|
||||||
|
tokenizer.expect("WS", expected="whitespace after 'not'")
|
||||||
|
tokenizer.expect("IN", expected="'in' after 'not'")
|
||||||
|
return Op("not in")
|
||||||
|
elif tokenizer.check("OP"):
|
||||||
|
return Op(tokenizer.read().text)
|
||||||
|
else:
|
||||||
|
return tokenizer.raise_syntax_error(
|
||||||
|
"Expected marker operator, one of "
|
||||||
|
"<=, <, !=, ==, >=, >, ~=, ===, in, not in"
|
||||||
|
)
|
||||||
|
|
@ -0,0 +1,61 @@
|
||||||
|
# This file is dual licensed under the terms of the Apache License, Version
|
||||||
|
# 2.0, and the BSD License. See the LICENSE file in the root of this repository
|
||||||
|
# for complete details.
|
||||||
|
|
||||||
|
|
||||||
|
class InfinityType:
|
||||||
|
def __repr__(self) -> str:
|
||||||
|
return "Infinity"
|
||||||
|
|
||||||
|
def __hash__(self) -> int:
|
||||||
|
return hash(repr(self))
|
||||||
|
|
||||||
|
def __lt__(self, other: object) -> bool:
|
||||||
|
return False
|
||||||
|
|
||||||
|
def __le__(self, other: object) -> bool:
|
||||||
|
return False
|
||||||
|
|
||||||
|
def __eq__(self, other: object) -> bool:
|
||||||
|
return isinstance(other, self.__class__)
|
||||||
|
|
||||||
|
def __gt__(self, other: object) -> bool:
|
||||||
|
return True
|
||||||
|
|
||||||
|
def __ge__(self, other: object) -> bool:
|
||||||
|
return True
|
||||||
|
|
||||||
|
def __neg__(self: object) -> "NegativeInfinityType":
|
||||||
|
return NegativeInfinity
|
||||||
|
|
||||||
|
|
||||||
|
Infinity = InfinityType()
|
||||||
|
|
||||||
|
|
||||||
|
class NegativeInfinityType:
|
||||||
|
def __repr__(self) -> str:
|
||||||
|
return "-Infinity"
|
||||||
|
|
||||||
|
def __hash__(self) -> int:
|
||||||
|
return hash(repr(self))
|
||||||
|
|
||||||
|
def __lt__(self, other: object) -> bool:
|
||||||
|
return True
|
||||||
|
|
||||||
|
def __le__(self, other: object) -> bool:
|
||||||
|
return True
|
||||||
|
|
||||||
|
def __eq__(self, other: object) -> bool:
|
||||||
|
return isinstance(other, self.__class__)
|
||||||
|
|
||||||
|
def __gt__(self, other: object) -> bool:
|
||||||
|
return False
|
||||||
|
|
||||||
|
def __ge__(self, other: object) -> bool:
|
||||||
|
return False
|
||||||
|
|
||||||
|
def __neg__(self: object) -> InfinityType:
|
||||||
|
return Infinity
|
||||||
|
|
||||||
|
|
||||||
|
NegativeInfinity = NegativeInfinityType()
|
||||||
|
|
@ -0,0 +1,192 @@
|
||||||
|
import contextlib
|
||||||
|
import re
|
||||||
|
from dataclasses import dataclass
|
||||||
|
from typing import Dict, Iterator, NoReturn, Optional, Tuple, Union
|
||||||
|
|
||||||
|
from .specifiers import Specifier
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class Token:
|
||||||
|
name: str
|
||||||
|
text: str
|
||||||
|
position: int
|
||||||
|
|
||||||
|
|
||||||
|
class ParserSyntaxError(Exception):
|
||||||
|
"""The provided source text could not be parsed correctly."""
|
||||||
|
|
||||||
|
def __init__(
|
||||||
|
self,
|
||||||
|
message: str,
|
||||||
|
*,
|
||||||
|
source: str,
|
||||||
|
span: Tuple[int, int],
|
||||||
|
) -> None:
|
||||||
|
self.span = span
|
||||||
|
self.message = message
|
||||||
|
self.source = source
|
||||||
|
|
||||||
|
super().__init__()
|
||||||
|
|
||||||
|
def __str__(self) -> str:
|
||||||
|
marker = " " * self.span[0] + "~" * (self.span[1] - self.span[0]) + "^"
|
||||||
|
return "\n ".join([self.message, self.source, marker])
|
||||||
|
|
||||||
|
|
||||||
|
DEFAULT_RULES: "Dict[str, Union[str, re.Pattern[str]]]" = {
|
||||||
|
"LEFT_PARENTHESIS": r"\(",
|
||||||
|
"RIGHT_PARENTHESIS": r"\)",
|
||||||
|
"LEFT_BRACKET": r"\[",
|
||||||
|
"RIGHT_BRACKET": r"\]",
|
||||||
|
"SEMICOLON": r";",
|
||||||
|
"COMMA": r",",
|
||||||
|
"QUOTED_STRING": re.compile(
|
||||||
|
r"""
|
||||||
|
(
|
||||||
|
('[^']*')
|
||||||
|
|
|
||||||
|
("[^"]*")
|
||||||
|
)
|
||||||
|
""",
|
||||||
|
re.VERBOSE,
|
||||||
|
),
|
||||||
|
"OP": r"(===|==|~=|!=|<=|>=|<|>)",
|
||||||
|
"BOOLOP": r"\b(or|and)\b",
|
||||||
|
"IN": r"\bin\b",
|
||||||
|
"NOT": r"\bnot\b",
|
||||||
|
"VARIABLE": re.compile(
|
||||||
|
r"""
|
||||||
|
\b(
|
||||||
|
python_version
|
||||||
|
|python_full_version
|
||||||
|
|os[._]name
|
||||||
|
|sys[._]platform
|
||||||
|
|platform_(release|system)
|
||||||
|
|platform[._](version|machine|python_implementation)
|
||||||
|
|python_implementation
|
||||||
|
|implementation_(name|version)
|
||||||
|
|extra
|
||||||
|
)\b
|
||||||
|
""",
|
||||||
|
re.VERBOSE,
|
||||||
|
),
|
||||||
|
"SPECIFIER": re.compile(
|
||||||
|
Specifier._operator_regex_str + Specifier._version_regex_str,
|
||||||
|
re.VERBOSE | re.IGNORECASE,
|
||||||
|
),
|
||||||
|
"AT": r"\@",
|
||||||
|
"URL": r"[^ \t]+",
|
||||||
|
"IDENTIFIER": r"\b[a-zA-Z0-9][a-zA-Z0-9._-]*\b",
|
||||||
|
"VERSION_PREFIX_TRAIL": r"\.\*",
|
||||||
|
"VERSION_LOCAL_LABEL_TRAIL": r"\+[a-z0-9]+(?:[-_\.][a-z0-9]+)*",
|
||||||
|
"WS": r"[ \t]+",
|
||||||
|
"END": r"$",
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
class Tokenizer:
|
||||||
|
"""Context-sensitive token parsing.
|
||||||
|
|
||||||
|
Provides methods to examine the input stream to check whether the next token
|
||||||
|
matches.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(
|
||||||
|
self,
|
||||||
|
source: str,
|
||||||
|
*,
|
||||||
|
rules: "Dict[str, Union[str, re.Pattern[str]]]",
|
||||||
|
) -> None:
|
||||||
|
self.source = source
|
||||||
|
self.rules: Dict[str, re.Pattern[str]] = {
|
||||||
|
name: re.compile(pattern) for name, pattern in rules.items()
|
||||||
|
}
|
||||||
|
self.next_token: Optional[Token] = None
|
||||||
|
self.position = 0
|
||||||
|
|
||||||
|
def consume(self, name: str) -> None:
|
||||||
|
"""Move beyond provided token name, if at current position."""
|
||||||
|
if self.check(name):
|
||||||
|
self.read()
|
||||||
|
|
||||||
|
def check(self, name: str, *, peek: bool = False) -> bool:
|
||||||
|
"""Check whether the next token has the provided name.
|
||||||
|
|
||||||
|
By default, if the check succeeds, the token *must* be read before
|
||||||
|
another check. If `peek` is set to `True`, the token is not loaded and
|
||||||
|
would need to be checked again.
|
||||||
|
"""
|
||||||
|
assert (
|
||||||
|
self.next_token is None
|
||||||
|
), f"Cannot check for {name!r}, already have {self.next_token!r}"
|
||||||
|
assert name in self.rules, f"Unknown token name: {name!r}"
|
||||||
|
|
||||||
|
expression = self.rules[name]
|
||||||
|
|
||||||
|
match = expression.match(self.source, self.position)
|
||||||
|
if match is None:
|
||||||
|
return False
|
||||||
|
if not peek:
|
||||||
|
self.next_token = Token(name, match[0], self.position)
|
||||||
|
return True
|
||||||
|
|
||||||
|
def expect(self, name: str, *, expected: str) -> Token:
|
||||||
|
"""Expect a certain token name next, failing with a syntax error otherwise.
|
||||||
|
|
||||||
|
The token is *not* read.
|
||||||
|
"""
|
||||||
|
if not self.check(name):
|
||||||
|
raise self.raise_syntax_error(f"Expected {expected}")
|
||||||
|
return self.read()
|
||||||
|
|
||||||
|
def read(self) -> Token:
|
||||||
|
"""Consume the next token and return it."""
|
||||||
|
token = self.next_token
|
||||||
|
assert token is not None
|
||||||
|
|
||||||
|
self.position += len(token.text)
|
||||||
|
self.next_token = None
|
||||||
|
|
||||||
|
return token
|
||||||
|
|
||||||
|
def raise_syntax_error(
|
||||||
|
self,
|
||||||
|
message: str,
|
||||||
|
*,
|
||||||
|
span_start: Optional[int] = None,
|
||||||
|
span_end: Optional[int] = None,
|
||||||
|
) -> NoReturn:
|
||||||
|
"""Raise ParserSyntaxError at the given position."""
|
||||||
|
span = (
|
||||||
|
self.position if span_start is None else span_start,
|
||||||
|
self.position if span_end is None else span_end,
|
||||||
|
)
|
||||||
|
raise ParserSyntaxError(
|
||||||
|
message,
|
||||||
|
source=self.source,
|
||||||
|
span=span,
|
||||||
|
)
|
||||||
|
|
||||||
|
@contextlib.contextmanager
|
||||||
|
def enclosing_tokens(
|
||||||
|
self, open_token: str, close_token: str, *, around: str
|
||||||
|
) -> Iterator[None]:
|
||||||
|
if self.check(open_token):
|
||||||
|
open_position = self.position
|
||||||
|
self.read()
|
||||||
|
else:
|
||||||
|
open_position = None
|
||||||
|
|
||||||
|
yield
|
||||||
|
|
||||||
|
if open_position is None:
|
||||||
|
return
|
||||||
|
|
||||||
|
if not self.check(close_token):
|
||||||
|
self.raise_syntax_error(
|
||||||
|
f"Expected matching {close_token} for {open_token}, after {around}",
|
||||||
|
span_start=open_position,
|
||||||
|
)
|
||||||
|
|
||||||
|
self.read()
|
||||||
|
|
@ -0,0 +1,252 @@
|
||||||
|
# This file is dual licensed under the terms of the Apache License, Version
|
||||||
|
# 2.0, and the BSD License. See the LICENSE file in the root of this repository
|
||||||
|
# for complete details.
|
||||||
|
|
||||||
|
import operator
|
||||||
|
import os
|
||||||
|
import platform
|
||||||
|
import sys
|
||||||
|
from typing import Any, Callable, Dict, List, Optional, Tuple, Union
|
||||||
|
|
||||||
|
from ._parser import (
|
||||||
|
MarkerAtom,
|
||||||
|
MarkerList,
|
||||||
|
Op,
|
||||||
|
Value,
|
||||||
|
Variable,
|
||||||
|
parse_marker as _parse_marker,
|
||||||
|
)
|
||||||
|
from ._tokenizer import ParserSyntaxError
|
||||||
|
from .specifiers import InvalidSpecifier, Specifier
|
||||||
|
from .utils import canonicalize_name
|
||||||
|
|
||||||
|
__all__ = [
|
||||||
|
"InvalidMarker",
|
||||||
|
"UndefinedComparison",
|
||||||
|
"UndefinedEnvironmentName",
|
||||||
|
"Marker",
|
||||||
|
"default_environment",
|
||||||
|
]
|
||||||
|
|
||||||
|
Operator = Callable[[str, str], bool]
|
||||||
|
|
||||||
|
|
||||||
|
class InvalidMarker(ValueError):
|
||||||
|
"""
|
||||||
|
An invalid marker was found, users should refer to PEP 508.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class UndefinedComparison(ValueError):
|
||||||
|
"""
|
||||||
|
An invalid operation was attempted on a value that doesn't support it.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class UndefinedEnvironmentName(ValueError):
|
||||||
|
"""
|
||||||
|
A name was attempted to be used that does not exist inside of the
|
||||||
|
environment.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
def _normalize_extra_values(results: Any) -> Any:
|
||||||
|
"""
|
||||||
|
Normalize extra values.
|
||||||
|
"""
|
||||||
|
if isinstance(results[0], tuple):
|
||||||
|
lhs, op, rhs = results[0]
|
||||||
|
if isinstance(lhs, Variable) and lhs.value == "extra":
|
||||||
|
normalized_extra = canonicalize_name(rhs.value)
|
||||||
|
rhs = Value(normalized_extra)
|
||||||
|
elif isinstance(rhs, Variable) and rhs.value == "extra":
|
||||||
|
normalized_extra = canonicalize_name(lhs.value)
|
||||||
|
lhs = Value(normalized_extra)
|
||||||
|
results[0] = lhs, op, rhs
|
||||||
|
return results
|
||||||
|
|
||||||
|
|
||||||
|
def _format_marker(
|
||||||
|
marker: Union[List[str], MarkerAtom, str], first: Optional[bool] = True
|
||||||
|
) -> str:
|
||||||
|
|
||||||
|
assert isinstance(marker, (list, tuple, str))
|
||||||
|
|
||||||
|
# Sometimes we have a structure like [[...]] which is a single item list
|
||||||
|
# where the single item is itself it's own list. In that case we want skip
|
||||||
|
# the rest of this function so that we don't get extraneous () on the
|
||||||
|
# outside.
|
||||||
|
if (
|
||||||
|
isinstance(marker, list)
|
||||||
|
and len(marker) == 1
|
||||||
|
and isinstance(marker[0], (list, tuple))
|
||||||
|
):
|
||||||
|
return _format_marker(marker[0])
|
||||||
|
|
||||||
|
if isinstance(marker, list):
|
||||||
|
inner = (_format_marker(m, first=False) for m in marker)
|
||||||
|
if first:
|
||||||
|
return " ".join(inner)
|
||||||
|
else:
|
||||||
|
return "(" + " ".join(inner) + ")"
|
||||||
|
elif isinstance(marker, tuple):
|
||||||
|
return " ".join([m.serialize() for m in marker])
|
||||||
|
else:
|
||||||
|
return marker
|
||||||
|
|
||||||
|
|
||||||
|
_operators: Dict[str, Operator] = {
|
||||||
|
"in": lambda lhs, rhs: lhs in rhs,
|
||||||
|
"not in": lambda lhs, rhs: lhs not in rhs,
|
||||||
|
"<": operator.lt,
|
||||||
|
"<=": operator.le,
|
||||||
|
"==": operator.eq,
|
||||||
|
"!=": operator.ne,
|
||||||
|
">=": operator.ge,
|
||||||
|
">": operator.gt,
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
def _eval_op(lhs: str, op: Op, rhs: str) -> bool:
|
||||||
|
try:
|
||||||
|
spec = Specifier("".join([op.serialize(), rhs]))
|
||||||
|
except InvalidSpecifier:
|
||||||
|
pass
|
||||||
|
else:
|
||||||
|
return spec.contains(lhs, prereleases=True)
|
||||||
|
|
||||||
|
oper: Optional[Operator] = _operators.get(op.serialize())
|
||||||
|
if oper is None:
|
||||||
|
raise UndefinedComparison(f"Undefined {op!r} on {lhs!r} and {rhs!r}.")
|
||||||
|
|
||||||
|
return oper(lhs, rhs)
|
||||||
|
|
||||||
|
|
||||||
|
def _normalize(*values: str, key: str) -> Tuple[str, ...]:
|
||||||
|
# PEP 685 – Comparison of extra names for optional distribution dependencies
|
||||||
|
# https://peps.python.org/pep-0685/
|
||||||
|
# > When comparing extra names, tools MUST normalize the names being
|
||||||
|
# > compared using the semantics outlined in PEP 503 for names
|
||||||
|
if key == "extra":
|
||||||
|
return tuple(canonicalize_name(v) for v in values)
|
||||||
|
|
||||||
|
# other environment markers don't have such standards
|
||||||
|
return values
|
||||||
|
|
||||||
|
|
||||||
|
def _evaluate_markers(markers: MarkerList, environment: Dict[str, str]) -> bool:
|
||||||
|
groups: List[List[bool]] = [[]]
|
||||||
|
|
||||||
|
for marker in markers:
|
||||||
|
assert isinstance(marker, (list, tuple, str))
|
||||||
|
|
||||||
|
if isinstance(marker, list):
|
||||||
|
groups[-1].append(_evaluate_markers(marker, environment))
|
||||||
|
elif isinstance(marker, tuple):
|
||||||
|
lhs, op, rhs = marker
|
||||||
|
|
||||||
|
if isinstance(lhs, Variable):
|
||||||
|
environment_key = lhs.value
|
||||||
|
lhs_value = environment[environment_key]
|
||||||
|
rhs_value = rhs.value
|
||||||
|
else:
|
||||||
|
lhs_value = lhs.value
|
||||||
|
environment_key = rhs.value
|
||||||
|
rhs_value = environment[environment_key]
|
||||||
|
|
||||||
|
lhs_value, rhs_value = _normalize(lhs_value, rhs_value, key=environment_key)
|
||||||
|
groups[-1].append(_eval_op(lhs_value, op, rhs_value))
|
||||||
|
else:
|
||||||
|
assert marker in ["and", "or"]
|
||||||
|
if marker == "or":
|
||||||
|
groups.append([])
|
||||||
|
|
||||||
|
return any(all(item) for item in groups)
|
||||||
|
|
||||||
|
|
||||||
|
def format_full_version(info: "sys._version_info") -> str:
|
||||||
|
version = "{0.major}.{0.minor}.{0.micro}".format(info)
|
||||||
|
kind = info.releaselevel
|
||||||
|
if kind != "final":
|
||||||
|
version += kind[0] + str(info.serial)
|
||||||
|
return version
|
||||||
|
|
||||||
|
|
||||||
|
def default_environment() -> Dict[str, str]:
|
||||||
|
iver = format_full_version(sys.implementation.version)
|
||||||
|
implementation_name = sys.implementation.name
|
||||||
|
return {
|
||||||
|
"implementation_name": implementation_name,
|
||||||
|
"implementation_version": iver,
|
||||||
|
"os_name": os.name,
|
||||||
|
"platform_machine": platform.machine(),
|
||||||
|
"platform_release": platform.release(),
|
||||||
|
"platform_system": platform.system(),
|
||||||
|
"platform_version": platform.version(),
|
||||||
|
"python_full_version": platform.python_version(),
|
||||||
|
"platform_python_implementation": platform.python_implementation(),
|
||||||
|
"python_version": ".".join(platform.python_version_tuple()[:2]),
|
||||||
|
"sys_platform": sys.platform,
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
class Marker:
|
||||||
|
def __init__(self, marker: str) -> None:
|
||||||
|
# Note: We create a Marker object without calling this constructor in
|
||||||
|
# packaging.requirements.Requirement. If any additional logic is
|
||||||
|
# added here, make sure to mirror/adapt Requirement.
|
||||||
|
try:
|
||||||
|
self._markers = _normalize_extra_values(_parse_marker(marker))
|
||||||
|
# The attribute `_markers` can be described in terms of a recursive type:
|
||||||
|
# MarkerList = List[Union[Tuple[Node, ...], str, MarkerList]]
|
||||||
|
#
|
||||||
|
# For example, the following expression:
|
||||||
|
# python_version > "3.6" or (python_version == "3.6" and os_name == "unix")
|
||||||
|
#
|
||||||
|
# is parsed into:
|
||||||
|
# [
|
||||||
|
# (<Variable('python_version')>, <Op('>')>, <Value('3.6')>),
|
||||||
|
# 'and',
|
||||||
|
# [
|
||||||
|
# (<Variable('python_version')>, <Op('==')>, <Value('3.6')>),
|
||||||
|
# 'or',
|
||||||
|
# (<Variable('os_name')>, <Op('==')>, <Value('unix')>)
|
||||||
|
# ]
|
||||||
|
# ]
|
||||||
|
except ParserSyntaxError as e:
|
||||||
|
raise InvalidMarker(str(e)) from e
|
||||||
|
|
||||||
|
def __str__(self) -> str:
|
||||||
|
return _format_marker(self._markers)
|
||||||
|
|
||||||
|
def __repr__(self) -> str:
|
||||||
|
return f"<Marker('{self}')>"
|
||||||
|
|
||||||
|
def __hash__(self) -> int:
|
||||||
|
return hash((self.__class__.__name__, str(self)))
|
||||||
|
|
||||||
|
def __eq__(self, other: Any) -> bool:
|
||||||
|
if not isinstance(other, Marker):
|
||||||
|
return NotImplemented
|
||||||
|
|
||||||
|
return str(self) == str(other)
|
||||||
|
|
||||||
|
def evaluate(self, environment: Optional[Dict[str, str]] = None) -> bool:
|
||||||
|
"""Evaluate a marker.
|
||||||
|
|
||||||
|
Return the boolean from evaluating the given marker against the
|
||||||
|
environment. environment is an optional argument to override all or
|
||||||
|
part of the determined environment.
|
||||||
|
|
||||||
|
The environment is determined from the current Python process.
|
||||||
|
"""
|
||||||
|
current_environment = default_environment()
|
||||||
|
current_environment["extra"] = ""
|
||||||
|
if environment is not None:
|
||||||
|
current_environment.update(environment)
|
||||||
|
# The API used to allow setting extra to None. We need to handle this
|
||||||
|
# case for backwards compatibility.
|
||||||
|
if current_environment["extra"] is None:
|
||||||
|
current_environment["extra"] = ""
|
||||||
|
|
||||||
|
return _evaluate_markers(self._markers, current_environment)
|
||||||
|
|
@ -0,0 +1,825 @@
|
||||||
|
import email.feedparser
|
||||||
|
import email.header
|
||||||
|
import email.message
|
||||||
|
import email.parser
|
||||||
|
import email.policy
|
||||||
|
import sys
|
||||||
|
import typing
|
||||||
|
from typing import (
|
||||||
|
Any,
|
||||||
|
Callable,
|
||||||
|
Dict,
|
||||||
|
Generic,
|
||||||
|
List,
|
||||||
|
Optional,
|
||||||
|
Tuple,
|
||||||
|
Type,
|
||||||
|
Union,
|
||||||
|
cast,
|
||||||
|
)
|
||||||
|
|
||||||
|
from . import requirements, specifiers, utils, version as version_module
|
||||||
|
|
||||||
|
T = typing.TypeVar("T")
|
||||||
|
if sys.version_info[:2] >= (3, 8): # pragma: no cover
|
||||||
|
from typing import Literal, TypedDict
|
||||||
|
else: # pragma: no cover
|
||||||
|
if typing.TYPE_CHECKING:
|
||||||
|
from typing_extensions import Literal, TypedDict
|
||||||
|
else:
|
||||||
|
try:
|
||||||
|
from typing_extensions import Literal, TypedDict
|
||||||
|
except ImportError:
|
||||||
|
|
||||||
|
class Literal:
|
||||||
|
def __init_subclass__(*_args, **_kwargs):
|
||||||
|
pass
|
||||||
|
|
||||||
|
class TypedDict:
|
||||||
|
def __init_subclass__(*_args, **_kwargs):
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
try:
|
||||||
|
ExceptionGroup
|
||||||
|
except NameError: # pragma: no cover
|
||||||
|
|
||||||
|
class ExceptionGroup(Exception): # noqa: N818
|
||||||
|
"""A minimal implementation of :external:exc:`ExceptionGroup` from Python 3.11.
|
||||||
|
|
||||||
|
If :external:exc:`ExceptionGroup` is already defined by Python itself,
|
||||||
|
that version is used instead.
|
||||||
|
"""
|
||||||
|
|
||||||
|
message: str
|
||||||
|
exceptions: List[Exception]
|
||||||
|
|
||||||
|
def __init__(self, message: str, exceptions: List[Exception]) -> None:
|
||||||
|
self.message = message
|
||||||
|
self.exceptions = exceptions
|
||||||
|
|
||||||
|
def __repr__(self) -> str:
|
||||||
|
return f"{self.__class__.__name__}({self.message!r}, {self.exceptions!r})"
|
||||||
|
|
||||||
|
else: # pragma: no cover
|
||||||
|
ExceptionGroup = ExceptionGroup
|
||||||
|
|
||||||
|
|
||||||
|
class InvalidMetadata(ValueError):
|
||||||
|
"""A metadata field contains invalid data."""
|
||||||
|
|
||||||
|
field: str
|
||||||
|
"""The name of the field that contains invalid data."""
|
||||||
|
|
||||||
|
def __init__(self, field: str, message: str) -> None:
|
||||||
|
self.field = field
|
||||||
|
super().__init__(message)
|
||||||
|
|
||||||
|
|
||||||
|
# The RawMetadata class attempts to make as few assumptions about the underlying
|
||||||
|
# serialization formats as possible. The idea is that as long as a serialization
|
||||||
|
# formats offer some very basic primitives in *some* way then we can support
|
||||||
|
# serializing to and from that format.
|
||||||
|
class RawMetadata(TypedDict, total=False):
|
||||||
|
"""A dictionary of raw core metadata.
|
||||||
|
|
||||||
|
Each field in core metadata maps to a key of this dictionary (when data is
|
||||||
|
provided). The key is lower-case and underscores are used instead of dashes
|
||||||
|
compared to the equivalent core metadata field. Any core metadata field that
|
||||||
|
can be specified multiple times or can hold multiple values in a single
|
||||||
|
field have a key with a plural name. See :class:`Metadata` whose attributes
|
||||||
|
match the keys of this dictionary.
|
||||||
|
|
||||||
|
Core metadata fields that can be specified multiple times are stored as a
|
||||||
|
list or dict depending on which is appropriate for the field. Any fields
|
||||||
|
which hold multiple values in a single field are stored as a list.
|
||||||
|
|
||||||
|
"""
|
||||||
|
|
||||||
|
# Metadata 1.0 - PEP 241
|
||||||
|
metadata_version: str
|
||||||
|
name: str
|
||||||
|
version: str
|
||||||
|
platforms: List[str]
|
||||||
|
summary: str
|
||||||
|
description: str
|
||||||
|
keywords: List[str]
|
||||||
|
home_page: str
|
||||||
|
author: str
|
||||||
|
author_email: str
|
||||||
|
license: str
|
||||||
|
|
||||||
|
# Metadata 1.1 - PEP 314
|
||||||
|
supported_platforms: List[str]
|
||||||
|
download_url: str
|
||||||
|
classifiers: List[str]
|
||||||
|
requires: List[str]
|
||||||
|
provides: List[str]
|
||||||
|
obsoletes: List[str]
|
||||||
|
|
||||||
|
# Metadata 1.2 - PEP 345
|
||||||
|
maintainer: str
|
||||||
|
maintainer_email: str
|
||||||
|
requires_dist: List[str]
|
||||||
|
provides_dist: List[str]
|
||||||
|
obsoletes_dist: List[str]
|
||||||
|
requires_python: str
|
||||||
|
requires_external: List[str]
|
||||||
|
project_urls: Dict[str, str]
|
||||||
|
|
||||||
|
# Metadata 2.0
|
||||||
|
# PEP 426 attempted to completely revamp the metadata format
|
||||||
|
# but got stuck without ever being able to build consensus on
|
||||||
|
# it and ultimately ended up withdrawn.
|
||||||
|
#
|
||||||
|
# However, a number of tools had started emitting METADATA with
|
||||||
|
# `2.0` Metadata-Version, so for historical reasons, this version
|
||||||
|
# was skipped.
|
||||||
|
|
||||||
|
# Metadata 2.1 - PEP 566
|
||||||
|
description_content_type: str
|
||||||
|
provides_extra: List[str]
|
||||||
|
|
||||||
|
# Metadata 2.2 - PEP 643
|
||||||
|
dynamic: List[str]
|
||||||
|
|
||||||
|
# Metadata 2.3 - PEP 685
|
||||||
|
# No new fields were added in PEP 685, just some edge case were
|
||||||
|
# tightened up to provide better interoptability.
|
||||||
|
|
||||||
|
|
||||||
|
_STRING_FIELDS = {
|
||||||
|
"author",
|
||||||
|
"author_email",
|
||||||
|
"description",
|
||||||
|
"description_content_type",
|
||||||
|
"download_url",
|
||||||
|
"home_page",
|
||||||
|
"license",
|
||||||
|
"maintainer",
|
||||||
|
"maintainer_email",
|
||||||
|
"metadata_version",
|
||||||
|
"name",
|
||||||
|
"requires_python",
|
||||||
|
"summary",
|
||||||
|
"version",
|
||||||
|
}
|
||||||
|
|
||||||
|
_LIST_FIELDS = {
|
||||||
|
"classifiers",
|
||||||
|
"dynamic",
|
||||||
|
"obsoletes",
|
||||||
|
"obsoletes_dist",
|
||||||
|
"platforms",
|
||||||
|
"provides",
|
||||||
|
"provides_dist",
|
||||||
|
"provides_extra",
|
||||||
|
"requires",
|
||||||
|
"requires_dist",
|
||||||
|
"requires_external",
|
||||||
|
"supported_platforms",
|
||||||
|
}
|
||||||
|
|
||||||
|
_DICT_FIELDS = {
|
||||||
|
"project_urls",
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
def _parse_keywords(data: str) -> List[str]:
|
||||||
|
"""Split a string of comma-separate keyboards into a list of keywords."""
|
||||||
|
return [k.strip() for k in data.split(",")]
|
||||||
|
|
||||||
|
|
||||||
|
def _parse_project_urls(data: List[str]) -> Dict[str, str]:
|
||||||
|
"""Parse a list of label/URL string pairings separated by a comma."""
|
||||||
|
urls = {}
|
||||||
|
for pair in data:
|
||||||
|
# Our logic is slightly tricky here as we want to try and do
|
||||||
|
# *something* reasonable with malformed data.
|
||||||
|
#
|
||||||
|
# The main thing that we have to worry about, is data that does
|
||||||
|
# not have a ',' at all to split the label from the Value. There
|
||||||
|
# isn't a singular right answer here, and we will fail validation
|
||||||
|
# later on (if the caller is validating) so it doesn't *really*
|
||||||
|
# matter, but since the missing value has to be an empty str
|
||||||
|
# and our return value is dict[str, str], if we let the key
|
||||||
|
# be the missing value, then they'd have multiple '' values that
|
||||||
|
# overwrite each other in a accumulating dict.
|
||||||
|
#
|
||||||
|
# The other potentional issue is that it's possible to have the
|
||||||
|
# same label multiple times in the metadata, with no solid "right"
|
||||||
|
# answer with what to do in that case. As such, we'll do the only
|
||||||
|
# thing we can, which is treat the field as unparseable and add it
|
||||||
|
# to our list of unparsed fields.
|
||||||
|
parts = [p.strip() for p in pair.split(",", 1)]
|
||||||
|
parts.extend([""] * (max(0, 2 - len(parts)))) # Ensure 2 items
|
||||||
|
|
||||||
|
# TODO: The spec doesn't say anything about if the keys should be
|
||||||
|
# considered case sensitive or not... logically they should
|
||||||
|
# be case-preserving and case-insensitive, but doing that
|
||||||
|
# would open up more cases where we might have duplicate
|
||||||
|
# entries.
|
||||||
|
label, url = parts
|
||||||
|
if label in urls:
|
||||||
|
# The label already exists in our set of urls, so this field
|
||||||
|
# is unparseable, and we can just add the whole thing to our
|
||||||
|
# unparseable data and stop processing it.
|
||||||
|
raise KeyError("duplicate labels in project urls")
|
||||||
|
urls[label] = url
|
||||||
|
|
||||||
|
return urls
|
||||||
|
|
||||||
|
|
||||||
|
def _get_payload(msg: email.message.Message, source: Union[bytes, str]) -> str:
|
||||||
|
"""Get the body of the message."""
|
||||||
|
# If our source is a str, then our caller has managed encodings for us,
|
||||||
|
# and we don't need to deal with it.
|
||||||
|
if isinstance(source, str):
|
||||||
|
payload: str = msg.get_payload()
|
||||||
|
return payload
|
||||||
|
# If our source is a bytes, then we're managing the encoding and we need
|
||||||
|
# to deal with it.
|
||||||
|
else:
|
||||||
|
bpayload: bytes = msg.get_payload(decode=True)
|
||||||
|
try:
|
||||||
|
return bpayload.decode("utf8", "strict")
|
||||||
|
except UnicodeDecodeError:
|
||||||
|
raise ValueError("payload in an invalid encoding")
|
||||||
|
|
||||||
|
|
||||||
|
# The various parse_FORMAT functions here are intended to be as lenient as
|
||||||
|
# possible in their parsing, while still returning a correctly typed
|
||||||
|
# RawMetadata.
|
||||||
|
#
|
||||||
|
# To aid in this, we also generally want to do as little touching of the
|
||||||
|
# data as possible, except where there are possibly some historic holdovers
|
||||||
|
# that make valid data awkward to work with.
|
||||||
|
#
|
||||||
|
# While this is a lower level, intermediate format than our ``Metadata``
|
||||||
|
# class, some light touch ups can make a massive difference in usability.
|
||||||
|
|
||||||
|
# Map METADATA fields to RawMetadata.
|
||||||
|
_EMAIL_TO_RAW_MAPPING = {
|
||||||
|
"author": "author",
|
||||||
|
"author-email": "author_email",
|
||||||
|
"classifier": "classifiers",
|
||||||
|
"description": "description",
|
||||||
|
"description-content-type": "description_content_type",
|
||||||
|
"download-url": "download_url",
|
||||||
|
"dynamic": "dynamic",
|
||||||
|
"home-page": "home_page",
|
||||||
|
"keywords": "keywords",
|
||||||
|
"license": "license",
|
||||||
|
"maintainer": "maintainer",
|
||||||
|
"maintainer-email": "maintainer_email",
|
||||||
|
"metadata-version": "metadata_version",
|
||||||
|
"name": "name",
|
||||||
|
"obsoletes": "obsoletes",
|
||||||
|
"obsoletes-dist": "obsoletes_dist",
|
||||||
|
"platform": "platforms",
|
||||||
|
"project-url": "project_urls",
|
||||||
|
"provides": "provides",
|
||||||
|
"provides-dist": "provides_dist",
|
||||||
|
"provides-extra": "provides_extra",
|
||||||
|
"requires": "requires",
|
||||||
|
"requires-dist": "requires_dist",
|
||||||
|
"requires-external": "requires_external",
|
||||||
|
"requires-python": "requires_python",
|
||||||
|
"summary": "summary",
|
||||||
|
"supported-platform": "supported_platforms",
|
||||||
|
"version": "version",
|
||||||
|
}
|
||||||
|
_RAW_TO_EMAIL_MAPPING = {raw: email for email, raw in _EMAIL_TO_RAW_MAPPING.items()}
|
||||||
|
|
||||||
|
|
||||||
|
def parse_email(data: Union[bytes, str]) -> Tuple[RawMetadata, Dict[str, List[str]]]:
|
||||||
|
"""Parse a distribution's metadata stored as email headers (e.g. from ``METADATA``).
|
||||||
|
|
||||||
|
This function returns a two-item tuple of dicts. The first dict is of
|
||||||
|
recognized fields from the core metadata specification. Fields that can be
|
||||||
|
parsed and translated into Python's built-in types are converted
|
||||||
|
appropriately. All other fields are left as-is. Fields that are allowed to
|
||||||
|
appear multiple times are stored as lists.
|
||||||
|
|
||||||
|
The second dict contains all other fields from the metadata. This includes
|
||||||
|
any unrecognized fields. It also includes any fields which are expected to
|
||||||
|
be parsed into a built-in type but were not formatted appropriately. Finally,
|
||||||
|
any fields that are expected to appear only once but are repeated are
|
||||||
|
included in this dict.
|
||||||
|
|
||||||
|
"""
|
||||||
|
raw: Dict[str, Union[str, List[str], Dict[str, str]]] = {}
|
||||||
|
unparsed: Dict[str, List[str]] = {}
|
||||||
|
|
||||||
|
if isinstance(data, str):
|
||||||
|
parsed = email.parser.Parser(policy=email.policy.compat32).parsestr(data)
|
||||||
|
else:
|
||||||
|
parsed = email.parser.BytesParser(policy=email.policy.compat32).parsebytes(data)
|
||||||
|
|
||||||
|
# We have to wrap parsed.keys() in a set, because in the case of multiple
|
||||||
|
# values for a key (a list), the key will appear multiple times in the
|
||||||
|
# list of keys, but we're avoiding that by using get_all().
|
||||||
|
for name in frozenset(parsed.keys()):
|
||||||
|
# Header names in RFC are case insensitive, so we'll normalize to all
|
||||||
|
# lower case to make comparisons easier.
|
||||||
|
name = name.lower()
|
||||||
|
|
||||||
|
# We use get_all() here, even for fields that aren't multiple use,
|
||||||
|
# because otherwise someone could have e.g. two Name fields, and we
|
||||||
|
# would just silently ignore it rather than doing something about it.
|
||||||
|
headers = parsed.get_all(name) or []
|
||||||
|
|
||||||
|
# The way the email module works when parsing bytes is that it
|
||||||
|
# unconditionally decodes the bytes as ascii using the surrogateescape
|
||||||
|
# handler. When you pull that data back out (such as with get_all() ),
|
||||||
|
# it looks to see if the str has any surrogate escapes, and if it does
|
||||||
|
# it wraps it in a Header object instead of returning the string.
|
||||||
|
#
|
||||||
|
# As such, we'll look for those Header objects, and fix up the encoding.
|
||||||
|
value = []
|
||||||
|
# Flag if we have run into any issues processing the headers, thus
|
||||||
|
# signalling that the data belongs in 'unparsed'.
|
||||||
|
valid_encoding = True
|
||||||
|
for h in headers:
|
||||||
|
# It's unclear if this can return more types than just a Header or
|
||||||
|
# a str, so we'll just assert here to make sure.
|
||||||
|
assert isinstance(h, (email.header.Header, str))
|
||||||
|
|
||||||
|
# If it's a header object, we need to do our little dance to get
|
||||||
|
# the real data out of it. In cases where there is invalid data
|
||||||
|
# we're going to end up with mojibake, but there's no obvious, good
|
||||||
|
# way around that without reimplementing parts of the Header object
|
||||||
|
# ourselves.
|
||||||
|
#
|
||||||
|
# That should be fine since, if mojibacked happens, this key is
|
||||||
|
# going into the unparsed dict anyways.
|
||||||
|
if isinstance(h, email.header.Header):
|
||||||
|
# The Header object stores it's data as chunks, and each chunk
|
||||||
|
# can be independently encoded, so we'll need to check each
|
||||||
|
# of them.
|
||||||
|
chunks: List[Tuple[bytes, Optional[str]]] = []
|
||||||
|
for bin, encoding in email.header.decode_header(h):
|
||||||
|
try:
|
||||||
|
bin.decode("utf8", "strict")
|
||||||
|
except UnicodeDecodeError:
|
||||||
|
# Enable mojibake.
|
||||||
|
encoding = "latin1"
|
||||||
|
valid_encoding = False
|
||||||
|
else:
|
||||||
|
encoding = "utf8"
|
||||||
|
chunks.append((bin, encoding))
|
||||||
|
|
||||||
|
# Turn our chunks back into a Header object, then let that
|
||||||
|
# Header object do the right thing to turn them into a
|
||||||
|
# string for us.
|
||||||
|
value.append(str(email.header.make_header(chunks)))
|
||||||
|
# This is already a string, so just add it.
|
||||||
|
else:
|
||||||
|
value.append(h)
|
||||||
|
|
||||||
|
# We've processed all of our values to get them into a list of str,
|
||||||
|
# but we may have mojibake data, in which case this is an unparsed
|
||||||
|
# field.
|
||||||
|
if not valid_encoding:
|
||||||
|
unparsed[name] = value
|
||||||
|
continue
|
||||||
|
|
||||||
|
raw_name = _EMAIL_TO_RAW_MAPPING.get(name)
|
||||||
|
if raw_name is None:
|
||||||
|
# This is a bit of a weird situation, we've encountered a key that
|
||||||
|
# we don't know what it means, so we don't know whether it's meant
|
||||||
|
# to be a list or not.
|
||||||
|
#
|
||||||
|
# Since we can't really tell one way or another, we'll just leave it
|
||||||
|
# as a list, even though it may be a single item list, because that's
|
||||||
|
# what makes the most sense for email headers.
|
||||||
|
unparsed[name] = value
|
||||||
|
continue
|
||||||
|
|
||||||
|
# If this is one of our string fields, then we'll check to see if our
|
||||||
|
# value is a list of a single item. If it is then we'll assume that
|
||||||
|
# it was emitted as a single string, and unwrap the str from inside
|
||||||
|
# the list.
|
||||||
|
#
|
||||||
|
# If it's any other kind of data, then we haven't the faintest clue
|
||||||
|
# what we should parse it as, and we have to just add it to our list
|
||||||
|
# of unparsed stuff.
|
||||||
|
if raw_name in _STRING_FIELDS and len(value) == 1:
|
||||||
|
raw[raw_name] = value[0]
|
||||||
|
# If this is one of our list of string fields, then we can just assign
|
||||||
|
# the value, since email *only* has strings, and our get_all() call
|
||||||
|
# above ensures that this is a list.
|
||||||
|
elif raw_name in _LIST_FIELDS:
|
||||||
|
raw[raw_name] = value
|
||||||
|
# Special Case: Keywords
|
||||||
|
# The keywords field is implemented in the metadata spec as a str,
|
||||||
|
# but it conceptually is a list of strings, and is serialized using
|
||||||
|
# ", ".join(keywords), so we'll do some light data massaging to turn
|
||||||
|
# this into what it logically is.
|
||||||
|
elif raw_name == "keywords" and len(value) == 1:
|
||||||
|
raw[raw_name] = _parse_keywords(value[0])
|
||||||
|
# Special Case: Project-URL
|
||||||
|
# The project urls is implemented in the metadata spec as a list of
|
||||||
|
# specially-formatted strings that represent a key and a value, which
|
||||||
|
# is fundamentally a mapping, however the email format doesn't support
|
||||||
|
# mappings in a sane way, so it was crammed into a list of strings
|
||||||
|
# instead.
|
||||||
|
#
|
||||||
|
# We will do a little light data massaging to turn this into a map as
|
||||||
|
# it logically should be.
|
||||||
|
elif raw_name == "project_urls":
|
||||||
|
try:
|
||||||
|
raw[raw_name] = _parse_project_urls(value)
|
||||||
|
except KeyError:
|
||||||
|
unparsed[name] = value
|
||||||
|
# Nothing that we've done has managed to parse this, so it'll just
|
||||||
|
# throw it in our unparseable data and move on.
|
||||||
|
else:
|
||||||
|
unparsed[name] = value
|
||||||
|
|
||||||
|
# We need to support getting the Description from the message payload in
|
||||||
|
# addition to getting it from the the headers. This does mean, though, there
|
||||||
|
# is the possibility of it being set both ways, in which case we put both
|
||||||
|
# in 'unparsed' since we don't know which is right.
|
||||||
|
try:
|
||||||
|
payload = _get_payload(parsed, data)
|
||||||
|
except ValueError:
|
||||||
|
unparsed.setdefault("description", []).append(
|
||||||
|
parsed.get_payload(decode=isinstance(data, bytes))
|
||||||
|
)
|
||||||
|
else:
|
||||||
|
if payload:
|
||||||
|
# Check to see if we've already got a description, if so then both
|
||||||
|
# it, and this body move to unparseable.
|
||||||
|
if "description" in raw:
|
||||||
|
description_header = cast(str, raw.pop("description"))
|
||||||
|
unparsed.setdefault("description", []).extend(
|
||||||
|
[description_header, payload]
|
||||||
|
)
|
||||||
|
elif "description" in unparsed:
|
||||||
|
unparsed["description"].append(payload)
|
||||||
|
else:
|
||||||
|
raw["description"] = payload
|
||||||
|
|
||||||
|
# We need to cast our `raw` to a metadata, because a TypedDict only support
|
||||||
|
# literal key names, but we're computing our key names on purpose, but the
|
||||||
|
# way this function is implemented, our `TypedDict` can only have valid key
|
||||||
|
# names.
|
||||||
|
return cast(RawMetadata, raw), unparsed
|
||||||
|
|
||||||
|
|
||||||
|
_NOT_FOUND = object()
|
||||||
|
|
||||||
|
|
||||||
|
# Keep the two values in sync.
|
||||||
|
_VALID_METADATA_VERSIONS = ["1.0", "1.1", "1.2", "2.1", "2.2", "2.3"]
|
||||||
|
_MetadataVersion = Literal["1.0", "1.1", "1.2", "2.1", "2.2", "2.3"]
|
||||||
|
|
||||||
|
_REQUIRED_ATTRS = frozenset(["metadata_version", "name", "version"])
|
||||||
|
|
||||||
|
|
||||||
|
class _Validator(Generic[T]):
|
||||||
|
"""Validate a metadata field.
|
||||||
|
|
||||||
|
All _process_*() methods correspond to a core metadata field. The method is
|
||||||
|
called with the field's raw value. If the raw value is valid it is returned
|
||||||
|
in its "enriched" form (e.g. ``version.Version`` for the ``Version`` field).
|
||||||
|
If the raw value is invalid, :exc:`InvalidMetadata` is raised (with a cause
|
||||||
|
as appropriate).
|
||||||
|
"""
|
||||||
|
|
||||||
|
name: str
|
||||||
|
raw_name: str
|
||||||
|
added: _MetadataVersion
|
||||||
|
|
||||||
|
def __init__(
|
||||||
|
self,
|
||||||
|
*,
|
||||||
|
added: _MetadataVersion = "1.0",
|
||||||
|
) -> None:
|
||||||
|
self.added = added
|
||||||
|
|
||||||
|
def __set_name__(self, _owner: "Metadata", name: str) -> None:
|
||||||
|
self.name = name
|
||||||
|
self.raw_name = _RAW_TO_EMAIL_MAPPING[name]
|
||||||
|
|
||||||
|
def __get__(self, instance: "Metadata", _owner: Type["Metadata"]) -> T:
|
||||||
|
# With Python 3.8, the caching can be replaced with functools.cached_property().
|
||||||
|
# No need to check the cache as attribute lookup will resolve into the
|
||||||
|
# instance's __dict__ before __get__ is called.
|
||||||
|
cache = instance.__dict__
|
||||||
|
value = instance._raw.get(self.name)
|
||||||
|
|
||||||
|
# To make the _process_* methods easier, we'll check if the value is None
|
||||||
|
# and if this field is NOT a required attribute, and if both of those
|
||||||
|
# things are true, we'll skip the the converter. This will mean that the
|
||||||
|
# converters never have to deal with the None union.
|
||||||
|
if self.name in _REQUIRED_ATTRS or value is not None:
|
||||||
|
try:
|
||||||
|
converter: Callable[[Any], T] = getattr(self, f"_process_{self.name}")
|
||||||
|
except AttributeError:
|
||||||
|
pass
|
||||||
|
else:
|
||||||
|
value = converter(value)
|
||||||
|
|
||||||
|
cache[self.name] = value
|
||||||
|
try:
|
||||||
|
del instance._raw[self.name] # type: ignore[misc]
|
||||||
|
except KeyError:
|
||||||
|
pass
|
||||||
|
|
||||||
|
return cast(T, value)
|
||||||
|
|
||||||
|
def _invalid_metadata(
|
||||||
|
self, msg: str, cause: Optional[Exception] = None
|
||||||
|
) -> InvalidMetadata:
|
||||||
|
exc = InvalidMetadata(
|
||||||
|
self.raw_name, msg.format_map({"field": repr(self.raw_name)})
|
||||||
|
)
|
||||||
|
exc.__cause__ = cause
|
||||||
|
return exc
|
||||||
|
|
||||||
|
def _process_metadata_version(self, value: str) -> _MetadataVersion:
|
||||||
|
# Implicitly makes Metadata-Version required.
|
||||||
|
if value not in _VALID_METADATA_VERSIONS:
|
||||||
|
raise self._invalid_metadata(f"{value!r} is not a valid metadata version")
|
||||||
|
return cast(_MetadataVersion, value)
|
||||||
|
|
||||||
|
def _process_name(self, value: str) -> str:
|
||||||
|
if not value:
|
||||||
|
raise self._invalid_metadata("{field} is a required field")
|
||||||
|
# Validate the name as a side-effect.
|
||||||
|
try:
|
||||||
|
utils.canonicalize_name(value, validate=True)
|
||||||
|
except utils.InvalidName as exc:
|
||||||
|
raise self._invalid_metadata(
|
||||||
|
f"{value!r} is invalid for {{field}}", cause=exc
|
||||||
|
)
|
||||||
|
else:
|
||||||
|
return value
|
||||||
|
|
||||||
|
def _process_version(self, value: str) -> version_module.Version:
|
||||||
|
if not value:
|
||||||
|
raise self._invalid_metadata("{field} is a required field")
|
||||||
|
try:
|
||||||
|
return version_module.parse(value)
|
||||||
|
except version_module.InvalidVersion as exc:
|
||||||
|
raise self._invalid_metadata(
|
||||||
|
f"{value!r} is invalid for {{field}}", cause=exc
|
||||||
|
)
|
||||||
|
|
||||||
|
def _process_summary(self, value: str) -> str:
|
||||||
|
"""Check the field contains no newlines."""
|
||||||
|
if "\n" in value:
|
||||||
|
raise self._invalid_metadata("{field} must be a single line")
|
||||||
|
return value
|
||||||
|
|
||||||
|
def _process_description_content_type(self, value: str) -> str:
|
||||||
|
content_types = {"text/plain", "text/x-rst", "text/markdown"}
|
||||||
|
message = email.message.EmailMessage()
|
||||||
|
message["content-type"] = value
|
||||||
|
|
||||||
|
content_type, parameters = (
|
||||||
|
# Defaults to `text/plain` if parsing failed.
|
||||||
|
message.get_content_type().lower(),
|
||||||
|
message["content-type"].params,
|
||||||
|
)
|
||||||
|
# Check if content-type is valid or defaulted to `text/plain` and thus was
|
||||||
|
# not parseable.
|
||||||
|
if content_type not in content_types or content_type not in value.lower():
|
||||||
|
raise self._invalid_metadata(
|
||||||
|
f"{{field}} must be one of {list(content_types)}, not {value!r}"
|
||||||
|
)
|
||||||
|
|
||||||
|
charset = parameters.get("charset", "UTF-8")
|
||||||
|
if charset != "UTF-8":
|
||||||
|
raise self._invalid_metadata(
|
||||||
|
f"{{field}} can only specify the UTF-8 charset, not {list(charset)}"
|
||||||
|
)
|
||||||
|
|
||||||
|
markdown_variants = {"GFM", "CommonMark"}
|
||||||
|
variant = parameters.get("variant", "GFM") # Use an acceptable default.
|
||||||
|
if content_type == "text/markdown" and variant not in markdown_variants:
|
||||||
|
raise self._invalid_metadata(
|
||||||
|
f"valid Markdown variants for {{field}} are {list(markdown_variants)}, "
|
||||||
|
f"not {variant!r}",
|
||||||
|
)
|
||||||
|
return value
|
||||||
|
|
||||||
|
def _process_dynamic(self, value: List[str]) -> List[str]:
|
||||||
|
for dynamic_field in map(str.lower, value):
|
||||||
|
if dynamic_field in {"name", "version", "metadata-version"}:
|
||||||
|
raise self._invalid_metadata(
|
||||||
|
f"{value!r} is not allowed as a dynamic field"
|
||||||
|
)
|
||||||
|
elif dynamic_field not in _EMAIL_TO_RAW_MAPPING:
|
||||||
|
raise self._invalid_metadata(f"{value!r} is not a valid dynamic field")
|
||||||
|
return list(map(str.lower, value))
|
||||||
|
|
||||||
|
def _process_provides_extra(
|
||||||
|
self,
|
||||||
|
value: List[str],
|
||||||
|
) -> List[utils.NormalizedName]:
|
||||||
|
normalized_names = []
|
||||||
|
try:
|
||||||
|
for name in value:
|
||||||
|
normalized_names.append(utils.canonicalize_name(name, validate=True))
|
||||||
|
except utils.InvalidName as exc:
|
||||||
|
raise self._invalid_metadata(
|
||||||
|
f"{name!r} is invalid for {{field}}", cause=exc
|
||||||
|
)
|
||||||
|
else:
|
||||||
|
return normalized_names
|
||||||
|
|
||||||
|
def _process_requires_python(self, value: str) -> specifiers.SpecifierSet:
|
||||||
|
try:
|
||||||
|
return specifiers.SpecifierSet(value)
|
||||||
|
except specifiers.InvalidSpecifier as exc:
|
||||||
|
raise self._invalid_metadata(
|
||||||
|
f"{value!r} is invalid for {{field}}", cause=exc
|
||||||
|
)
|
||||||
|
|
||||||
|
def _process_requires_dist(
|
||||||
|
self,
|
||||||
|
value: List[str],
|
||||||
|
) -> List[requirements.Requirement]:
|
||||||
|
reqs = []
|
||||||
|
try:
|
||||||
|
for req in value:
|
||||||
|
reqs.append(requirements.Requirement(req))
|
||||||
|
except requirements.InvalidRequirement as exc:
|
||||||
|
raise self._invalid_metadata(f"{req!r} is invalid for {{field}}", cause=exc)
|
||||||
|
else:
|
||||||
|
return reqs
|
||||||
|
|
||||||
|
|
||||||
|
class Metadata:
|
||||||
|
"""Representation of distribution metadata.
|
||||||
|
|
||||||
|
Compared to :class:`RawMetadata`, this class provides objects representing
|
||||||
|
metadata fields instead of only using built-in types. Any invalid metadata
|
||||||
|
will cause :exc:`InvalidMetadata` to be raised (with a
|
||||||
|
:py:attr:`~BaseException.__cause__` attribute as appropriate).
|
||||||
|
"""
|
||||||
|
|
||||||
|
_raw: RawMetadata
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
def from_raw(cls, data: RawMetadata, *, validate: bool = True) -> "Metadata":
|
||||||
|
"""Create an instance from :class:`RawMetadata`.
|
||||||
|
|
||||||
|
If *validate* is true, all metadata will be validated. All exceptions
|
||||||
|
related to validation will be gathered and raised as an :class:`ExceptionGroup`.
|
||||||
|
"""
|
||||||
|
ins = cls()
|
||||||
|
ins._raw = data.copy() # Mutations occur due to caching enriched values.
|
||||||
|
|
||||||
|
if validate:
|
||||||
|
exceptions: List[Exception] = []
|
||||||
|
try:
|
||||||
|
metadata_version = ins.metadata_version
|
||||||
|
metadata_age = _VALID_METADATA_VERSIONS.index(metadata_version)
|
||||||
|
except InvalidMetadata as metadata_version_exc:
|
||||||
|
exceptions.append(metadata_version_exc)
|
||||||
|
metadata_version = None
|
||||||
|
|
||||||
|
# Make sure to check for the fields that are present, the required
|
||||||
|
# fields (so their absence can be reported).
|
||||||
|
fields_to_check = frozenset(ins._raw) | _REQUIRED_ATTRS
|
||||||
|
# Remove fields that have already been checked.
|
||||||
|
fields_to_check -= {"metadata_version"}
|
||||||
|
|
||||||
|
for key in fields_to_check:
|
||||||
|
try:
|
||||||
|
if metadata_version:
|
||||||
|
# Can't use getattr() as that triggers descriptor protocol which
|
||||||
|
# will fail due to no value for the instance argument.
|
||||||
|
try:
|
||||||
|
field_metadata_version = cls.__dict__[key].added
|
||||||
|
except KeyError:
|
||||||
|
exc = InvalidMetadata(key, f"unrecognized field: {key!r}")
|
||||||
|
exceptions.append(exc)
|
||||||
|
continue
|
||||||
|
field_age = _VALID_METADATA_VERSIONS.index(
|
||||||
|
field_metadata_version
|
||||||
|
)
|
||||||
|
if field_age > metadata_age:
|
||||||
|
field = _RAW_TO_EMAIL_MAPPING[key]
|
||||||
|
exc = InvalidMetadata(
|
||||||
|
field,
|
||||||
|
"{field} introduced in metadata version "
|
||||||
|
"{field_metadata_version}, not {metadata_version}",
|
||||||
|
)
|
||||||
|
exceptions.append(exc)
|
||||||
|
continue
|
||||||
|
getattr(ins, key)
|
||||||
|
except InvalidMetadata as exc:
|
||||||
|
exceptions.append(exc)
|
||||||
|
|
||||||
|
if exceptions:
|
||||||
|
raise ExceptionGroup("invalid metadata", exceptions)
|
||||||
|
|
||||||
|
return ins
|
||||||
|
|
||||||
|
@classmethod
|
||||||
|
def from_email(
|
||||||
|
cls, data: Union[bytes, str], *, validate: bool = True
|
||||||
|
) -> "Metadata":
|
||||||
|
"""Parse metadata from email headers.
|
||||||
|
|
||||||
|
If *validate* is true, the metadata will be validated. All exceptions
|
||||||
|
related to validation will be gathered and raised as an :class:`ExceptionGroup`.
|
||||||
|
"""
|
||||||
|
raw, unparsed = parse_email(data)
|
||||||
|
|
||||||
|
if validate:
|
||||||
|
exceptions: list[Exception] = []
|
||||||
|
for unparsed_key in unparsed:
|
||||||
|
if unparsed_key in _EMAIL_TO_RAW_MAPPING:
|
||||||
|
message = f"{unparsed_key!r} has invalid data"
|
||||||
|
else:
|
||||||
|
message = f"unrecognized field: {unparsed_key!r}"
|
||||||
|
exceptions.append(InvalidMetadata(unparsed_key, message))
|
||||||
|
|
||||||
|
if exceptions:
|
||||||
|
raise ExceptionGroup("unparsed", exceptions)
|
||||||
|
|
||||||
|
try:
|
||||||
|
return cls.from_raw(raw, validate=validate)
|
||||||
|
except ExceptionGroup as exc_group:
|
||||||
|
raise ExceptionGroup(
|
||||||
|
"invalid or unparsed metadata", exc_group.exceptions
|
||||||
|
) from None
|
||||||
|
|
||||||
|
metadata_version: _Validator[_MetadataVersion] = _Validator()
|
||||||
|
""":external:ref:`core-metadata-metadata-version`
|
||||||
|
(required; validated to be a valid metadata version)"""
|
||||||
|
name: _Validator[str] = _Validator()
|
||||||
|
""":external:ref:`core-metadata-name`
|
||||||
|
(required; validated using :func:`~packaging.utils.canonicalize_name` and its
|
||||||
|
*validate* parameter)"""
|
||||||
|
version: _Validator[version_module.Version] = _Validator()
|
||||||
|
""":external:ref:`core-metadata-version` (required)"""
|
||||||
|
dynamic: _Validator[Optional[List[str]]] = _Validator(
|
||||||
|
added="2.2",
|
||||||
|
)
|
||||||
|
""":external:ref:`core-metadata-dynamic`
|
||||||
|
(validated against core metadata field names and lowercased)"""
|
||||||
|
platforms: _Validator[Optional[List[str]]] = _Validator()
|
||||||
|
""":external:ref:`core-metadata-platform`"""
|
||||||
|
supported_platforms: _Validator[Optional[List[str]]] = _Validator(added="1.1")
|
||||||
|
""":external:ref:`core-metadata-supported-platform`"""
|
||||||
|
summary: _Validator[Optional[str]] = _Validator()
|
||||||
|
""":external:ref:`core-metadata-summary` (validated to contain no newlines)"""
|
||||||
|
description: _Validator[Optional[str]] = _Validator() # TODO 2.1: can be in body
|
||||||
|
""":external:ref:`core-metadata-description`"""
|
||||||
|
description_content_type: _Validator[Optional[str]] = _Validator(added="2.1")
|
||||||
|
""":external:ref:`core-metadata-description-content-type` (validated)"""
|
||||||
|
keywords: _Validator[Optional[List[str]]] = _Validator()
|
||||||
|
""":external:ref:`core-metadata-keywords`"""
|
||||||
|
home_page: _Validator[Optional[str]] = _Validator()
|
||||||
|
""":external:ref:`core-metadata-home-page`"""
|
||||||
|
download_url: _Validator[Optional[str]] = _Validator(added="1.1")
|
||||||
|
""":external:ref:`core-metadata-download-url`"""
|
||||||
|
author: _Validator[Optional[str]] = _Validator()
|
||||||
|
""":external:ref:`core-metadata-author`"""
|
||||||
|
author_email: _Validator[Optional[str]] = _Validator()
|
||||||
|
""":external:ref:`core-metadata-author-email`"""
|
||||||
|
maintainer: _Validator[Optional[str]] = _Validator(added="1.2")
|
||||||
|
""":external:ref:`core-metadata-maintainer`"""
|
||||||
|
maintainer_email: _Validator[Optional[str]] = _Validator(added="1.2")
|
||||||
|
""":external:ref:`core-metadata-maintainer-email`"""
|
||||||
|
license: _Validator[Optional[str]] = _Validator()
|
||||||
|
""":external:ref:`core-metadata-license`"""
|
||||||
|
classifiers: _Validator[Optional[List[str]]] = _Validator(added="1.1")
|
||||||
|
""":external:ref:`core-metadata-classifier`"""
|
||||||
|
requires_dist: _Validator[Optional[List[requirements.Requirement]]] = _Validator(
|
||||||
|
added="1.2"
|
||||||
|
)
|
||||||
|
""":external:ref:`core-metadata-requires-dist`"""
|
||||||
|
requires_python: _Validator[Optional[specifiers.SpecifierSet]] = _Validator(
|
||||||
|
added="1.2"
|
||||||
|
)
|
||||||
|
""":external:ref:`core-metadata-requires-python`"""
|
||||||
|
# Because `Requires-External` allows for non-PEP 440 version specifiers, we
|
||||||
|
# don't do any processing on the values.
|
||||||
|
requires_external: _Validator[Optional[List[str]]] = _Validator(added="1.2")
|
||||||
|
""":external:ref:`core-metadata-requires-external`"""
|
||||||
|
project_urls: _Validator[Optional[Dict[str, str]]] = _Validator(added="1.2")
|
||||||
|
""":external:ref:`core-metadata-project-url`"""
|
||||||
|
# PEP 685 lets us raise an error if an extra doesn't pass `Name` validation
|
||||||
|
# regardless of metadata version.
|
||||||
|
provides_extra: _Validator[Optional[List[utils.NormalizedName]]] = _Validator(
|
||||||
|
added="2.1",
|
||||||
|
)
|
||||||
|
""":external:ref:`core-metadata-provides-extra`"""
|
||||||
|
provides_dist: _Validator[Optional[List[str]]] = _Validator(added="1.2")
|
||||||
|
""":external:ref:`core-metadata-provides-dist`"""
|
||||||
|
obsoletes_dist: _Validator[Optional[List[str]]] = _Validator(added="1.2")
|
||||||
|
""":external:ref:`core-metadata-obsoletes-dist`"""
|
||||||
|
requires: _Validator[Optional[List[str]]] = _Validator(added="1.1")
|
||||||
|
"""``Requires`` (deprecated)"""
|
||||||
|
provides: _Validator[Optional[List[str]]] = _Validator(added="1.1")
|
||||||
|
"""``Provides`` (deprecated)"""
|
||||||
|
obsoletes: _Validator[Optional[List[str]]] = _Validator(added="1.1")
|
||||||
|
"""``Obsoletes`` (deprecated)"""
|
||||||
|
|
@ -0,0 +1,90 @@
|
||||||
|
# This file is dual licensed under the terms of the Apache License, Version
|
||||||
|
# 2.0, and the BSD License. See the LICENSE file in the root of this repository
|
||||||
|
# for complete details.
|
||||||
|
|
||||||
|
from typing import Any, Iterator, Optional, Set
|
||||||
|
|
||||||
|
from ._parser import parse_requirement as _parse_requirement
|
||||||
|
from ._tokenizer import ParserSyntaxError
|
||||||
|
from .markers import Marker, _normalize_extra_values
|
||||||
|
from .specifiers import SpecifierSet
|
||||||
|
from .utils import canonicalize_name
|
||||||
|
|
||||||
|
|
||||||
|
class InvalidRequirement(ValueError):
|
||||||
|
"""
|
||||||
|
An invalid requirement was found, users should refer to PEP 508.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class Requirement:
|
||||||
|
"""Parse a requirement.
|
||||||
|
|
||||||
|
Parse a given requirement string into its parts, such as name, specifier,
|
||||||
|
URL, and extras. Raises InvalidRequirement on a badly-formed requirement
|
||||||
|
string.
|
||||||
|
"""
|
||||||
|
|
||||||
|
# TODO: Can we test whether something is contained within a requirement?
|
||||||
|
# If so how do we do that? Do we need to test against the _name_ of
|
||||||
|
# the thing as well as the version? What about the markers?
|
||||||
|
# TODO: Can we normalize the name and extra name?
|
||||||
|
|
||||||
|
def __init__(self, requirement_string: str) -> None:
|
||||||
|
try:
|
||||||
|
parsed = _parse_requirement(requirement_string)
|
||||||
|
except ParserSyntaxError as e:
|
||||||
|
raise InvalidRequirement(str(e)) from e
|
||||||
|
|
||||||
|
self.name: str = parsed.name
|
||||||
|
self.url: Optional[str] = parsed.url or None
|
||||||
|
self.extras: Set[str] = set(parsed.extras or [])
|
||||||
|
self.specifier: SpecifierSet = SpecifierSet(parsed.specifier)
|
||||||
|
self.marker: Optional[Marker] = None
|
||||||
|
if parsed.marker is not None:
|
||||||
|
self.marker = Marker.__new__(Marker)
|
||||||
|
self.marker._markers = _normalize_extra_values(parsed.marker)
|
||||||
|
|
||||||
|
def _iter_parts(self, name: str) -> Iterator[str]:
|
||||||
|
yield name
|
||||||
|
|
||||||
|
if self.extras:
|
||||||
|
formatted_extras = ",".join(sorted(self.extras))
|
||||||
|
yield f"[{formatted_extras}]"
|
||||||
|
|
||||||
|
if self.specifier:
|
||||||
|
yield str(self.specifier)
|
||||||
|
|
||||||
|
if self.url:
|
||||||
|
yield f"@ {self.url}"
|
||||||
|
if self.marker:
|
||||||
|
yield " "
|
||||||
|
|
||||||
|
if self.marker:
|
||||||
|
yield f"; {self.marker}"
|
||||||
|
|
||||||
|
def __str__(self) -> str:
|
||||||
|
return "".join(self._iter_parts(self.name))
|
||||||
|
|
||||||
|
def __repr__(self) -> str:
|
||||||
|
return f"<Requirement('{self}')>"
|
||||||
|
|
||||||
|
def __hash__(self) -> int:
|
||||||
|
return hash(
|
||||||
|
(
|
||||||
|
self.__class__.__name__,
|
||||||
|
*self._iter_parts(canonicalize_name(self.name)),
|
||||||
|
)
|
||||||
|
)
|
||||||
|
|
||||||
|
def __eq__(self, other: Any) -> bool:
|
||||||
|
if not isinstance(other, Requirement):
|
||||||
|
return NotImplemented
|
||||||
|
|
||||||
|
return (
|
||||||
|
canonicalize_name(self.name) == canonicalize_name(other.name)
|
||||||
|
and self.extras == other.extras
|
||||||
|
and self.specifier == other.specifier
|
||||||
|
and self.url == other.url
|
||||||
|
and self.marker == other.marker
|
||||||
|
)
|
||||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,571 @@
|
||||||
|
# This file is dual licensed under the terms of the Apache License, Version
|
||||||
|
# 2.0, and the BSD License. See the LICENSE file in the root of this repository
|
||||||
|
# for complete details.
|
||||||
|
|
||||||
|
import logging
|
||||||
|
import platform
|
||||||
|
import re
|
||||||
|
import struct
|
||||||
|
import subprocess
|
||||||
|
import sys
|
||||||
|
import sysconfig
|
||||||
|
from importlib.machinery import EXTENSION_SUFFIXES
|
||||||
|
from typing import (
|
||||||
|
Dict,
|
||||||
|
FrozenSet,
|
||||||
|
Iterable,
|
||||||
|
Iterator,
|
||||||
|
List,
|
||||||
|
Optional,
|
||||||
|
Sequence,
|
||||||
|
Tuple,
|
||||||
|
Union,
|
||||||
|
cast,
|
||||||
|
)
|
||||||
|
|
||||||
|
from . import _manylinux, _musllinux
|
||||||
|
|
||||||
|
logger = logging.getLogger(__name__)
|
||||||
|
|
||||||
|
PythonVersion = Sequence[int]
|
||||||
|
MacVersion = Tuple[int, int]
|
||||||
|
|
||||||
|
INTERPRETER_SHORT_NAMES: Dict[str, str] = {
|
||||||
|
"python": "py", # Generic.
|
||||||
|
"cpython": "cp",
|
||||||
|
"pypy": "pp",
|
||||||
|
"ironpython": "ip",
|
||||||
|
"jython": "jy",
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
_32_BIT_INTERPRETER = struct.calcsize("P") == 4
|
||||||
|
|
||||||
|
|
||||||
|
class Tag:
|
||||||
|
"""
|
||||||
|
A representation of the tag triple for a wheel.
|
||||||
|
|
||||||
|
Instances are considered immutable and thus are hashable. Equality checking
|
||||||
|
is also supported.
|
||||||
|
"""
|
||||||
|
|
||||||
|
__slots__ = ["_interpreter", "_abi", "_platform", "_hash"]
|
||||||
|
|
||||||
|
def __init__(self, interpreter: str, abi: str, platform: str) -> None:
|
||||||
|
self._interpreter = interpreter.lower()
|
||||||
|
self._abi = abi.lower()
|
||||||
|
self._platform = platform.lower()
|
||||||
|
# The __hash__ of every single element in a Set[Tag] will be evaluated each time
|
||||||
|
# that a set calls its `.disjoint()` method, which may be called hundreds of
|
||||||
|
# times when scanning a page of links for packages with tags matching that
|
||||||
|
# Set[Tag]. Pre-computing the value here produces significant speedups for
|
||||||
|
# downstream consumers.
|
||||||
|
self._hash = hash((self._interpreter, self._abi, self._platform))
|
||||||
|
|
||||||
|
@property
|
||||||
|
def interpreter(self) -> str:
|
||||||
|
return self._interpreter
|
||||||
|
|
||||||
|
@property
|
||||||
|
def abi(self) -> str:
|
||||||
|
return self._abi
|
||||||
|
|
||||||
|
@property
|
||||||
|
def platform(self) -> str:
|
||||||
|
return self._platform
|
||||||
|
|
||||||
|
def __eq__(self, other: object) -> bool:
|
||||||
|
if not isinstance(other, Tag):
|
||||||
|
return NotImplemented
|
||||||
|
|
||||||
|
return (
|
||||||
|
(self._hash == other._hash) # Short-circuit ASAP for perf reasons.
|
||||||
|
and (self._platform == other._platform)
|
||||||
|
and (self._abi == other._abi)
|
||||||
|
and (self._interpreter == other._interpreter)
|
||||||
|
)
|
||||||
|
|
||||||
|
def __hash__(self) -> int:
|
||||||
|
return self._hash
|
||||||
|
|
||||||
|
def __str__(self) -> str:
|
||||||
|
return f"{self._interpreter}-{self._abi}-{self._platform}"
|
||||||
|
|
||||||
|
def __repr__(self) -> str:
|
||||||
|
return f"<{self} @ {id(self)}>"
|
||||||
|
|
||||||
|
|
||||||
|
def parse_tag(tag: str) -> FrozenSet[Tag]:
|
||||||
|
"""
|
||||||
|
Parses the provided tag (e.g. `py3-none-any`) into a frozenset of Tag instances.
|
||||||
|
|
||||||
|
Returning a set is required due to the possibility that the tag is a
|
||||||
|
compressed tag set.
|
||||||
|
"""
|
||||||
|
tags = set()
|
||||||
|
interpreters, abis, platforms = tag.split("-")
|
||||||
|
for interpreter in interpreters.split("."):
|
||||||
|
for abi in abis.split("."):
|
||||||
|
for platform_ in platforms.split("."):
|
||||||
|
tags.add(Tag(interpreter, abi, platform_))
|
||||||
|
return frozenset(tags)
|
||||||
|
|
||||||
|
|
||||||
|
def _get_config_var(name: str, warn: bool = False) -> Union[int, str, None]:
|
||||||
|
value: Union[int, str, None] = sysconfig.get_config_var(name)
|
||||||
|
if value is None and warn:
|
||||||
|
logger.debug(
|
||||||
|
"Config variable '%s' is unset, Python ABI tag may be incorrect", name
|
||||||
|
)
|
||||||
|
return value
|
||||||
|
|
||||||
|
|
||||||
|
def _normalize_string(string: str) -> str:
|
||||||
|
return string.replace(".", "_").replace("-", "_").replace(" ", "_")
|
||||||
|
|
||||||
|
|
||||||
|
def _is_threaded_cpython(abis: List[str]) -> bool:
|
||||||
|
"""
|
||||||
|
Determine if the ABI corresponds to a threaded (`--disable-gil`) build.
|
||||||
|
|
||||||
|
The threaded builds are indicated by a "t" in the abiflags.
|
||||||
|
"""
|
||||||
|
if len(abis) == 0:
|
||||||
|
return False
|
||||||
|
# expect e.g., cp313
|
||||||
|
m = re.match(r"cp\d+(.*)", abis[0])
|
||||||
|
if not m:
|
||||||
|
return False
|
||||||
|
abiflags = m.group(1)
|
||||||
|
return "t" in abiflags
|
||||||
|
|
||||||
|
|
||||||
|
def _abi3_applies(python_version: PythonVersion, threading: bool) -> bool:
|
||||||
|
"""
|
||||||
|
Determine if the Python version supports abi3.
|
||||||
|
|
||||||
|
PEP 384 was first implemented in Python 3.2. The threaded (`--disable-gil`)
|
||||||
|
builds do not support abi3.
|
||||||
|
"""
|
||||||
|
return len(python_version) > 1 and tuple(python_version) >= (3, 2) and not threading
|
||||||
|
|
||||||
|
|
||||||
|
def _cpython_abis(py_version: PythonVersion, warn: bool = False) -> List[str]:
|
||||||
|
py_version = tuple(py_version) # To allow for version comparison.
|
||||||
|
abis = []
|
||||||
|
version = _version_nodot(py_version[:2])
|
||||||
|
threading = debug = pymalloc = ucs4 = ""
|
||||||
|
with_debug = _get_config_var("Py_DEBUG", warn)
|
||||||
|
has_refcount = hasattr(sys, "gettotalrefcount")
|
||||||
|
# Windows doesn't set Py_DEBUG, so checking for support of debug-compiled
|
||||||
|
# extension modules is the best option.
|
||||||
|
# https://github.com/pypa/pip/issues/3383#issuecomment-173267692
|
||||||
|
has_ext = "_d.pyd" in EXTENSION_SUFFIXES
|
||||||
|
if with_debug or (with_debug is None and (has_refcount or has_ext)):
|
||||||
|
debug = "d"
|
||||||
|
if py_version >= (3, 13) and _get_config_var("Py_GIL_DISABLED", warn):
|
||||||
|
threading = "t"
|
||||||
|
if py_version < (3, 8):
|
||||||
|
with_pymalloc = _get_config_var("WITH_PYMALLOC", warn)
|
||||||
|
if with_pymalloc or with_pymalloc is None:
|
||||||
|
pymalloc = "m"
|
||||||
|
if py_version < (3, 3):
|
||||||
|
unicode_size = _get_config_var("Py_UNICODE_SIZE", warn)
|
||||||
|
if unicode_size == 4 or (
|
||||||
|
unicode_size is None and sys.maxunicode == 0x10FFFF
|
||||||
|
):
|
||||||
|
ucs4 = "u"
|
||||||
|
elif debug:
|
||||||
|
# Debug builds can also load "normal" extension modules.
|
||||||
|
# We can also assume no UCS-4 or pymalloc requirement.
|
||||||
|
abis.append(f"cp{version}{threading}")
|
||||||
|
abis.insert(0, f"cp{version}{threading}{debug}{pymalloc}{ucs4}")
|
||||||
|
return abis
|
||||||
|
|
||||||
|
|
||||||
|
def cpython_tags(
|
||||||
|
python_version: Optional[PythonVersion] = None,
|
||||||
|
abis: Optional[Iterable[str]] = None,
|
||||||
|
platforms: Optional[Iterable[str]] = None,
|
||||||
|
*,
|
||||||
|
warn: bool = False,
|
||||||
|
) -> Iterator[Tag]:
|
||||||
|
"""
|
||||||
|
Yields the tags for a CPython interpreter.
|
||||||
|
|
||||||
|
The tags consist of:
|
||||||
|
- cp<python_version>-<abi>-<platform>
|
||||||
|
- cp<python_version>-abi3-<platform>
|
||||||
|
- cp<python_version>-none-<platform>
|
||||||
|
- cp<less than python_version>-abi3-<platform> # Older Python versions down to 3.2.
|
||||||
|
|
||||||
|
If python_version only specifies a major version then user-provided ABIs and
|
||||||
|
the 'none' ABItag will be used.
|
||||||
|
|
||||||
|
If 'abi3' or 'none' are specified in 'abis' then they will be yielded at
|
||||||
|
their normal position and not at the beginning.
|
||||||
|
"""
|
||||||
|
if not python_version:
|
||||||
|
python_version = sys.version_info[:2]
|
||||||
|
|
||||||
|
interpreter = f"cp{_version_nodot(python_version[:2])}"
|
||||||
|
|
||||||
|
if abis is None:
|
||||||
|
if len(python_version) > 1:
|
||||||
|
abis = _cpython_abis(python_version, warn)
|
||||||
|
else:
|
||||||
|
abis = []
|
||||||
|
abis = list(abis)
|
||||||
|
# 'abi3' and 'none' are explicitly handled later.
|
||||||
|
for explicit_abi in ("abi3", "none"):
|
||||||
|
try:
|
||||||
|
abis.remove(explicit_abi)
|
||||||
|
except ValueError:
|
||||||
|
pass
|
||||||
|
|
||||||
|
platforms = list(platforms or platform_tags())
|
||||||
|
for abi in abis:
|
||||||
|
for platform_ in platforms:
|
||||||
|
yield Tag(interpreter, abi, platform_)
|
||||||
|
|
||||||
|
threading = _is_threaded_cpython(abis)
|
||||||
|
use_abi3 = _abi3_applies(python_version, threading)
|
||||||
|
if use_abi3:
|
||||||
|
yield from (Tag(interpreter, "abi3", platform_) for platform_ in platforms)
|
||||||
|
yield from (Tag(interpreter, "none", platform_) for platform_ in platforms)
|
||||||
|
|
||||||
|
if use_abi3:
|
||||||
|
for minor_version in range(python_version[1] - 1, 1, -1):
|
||||||
|
for platform_ in platforms:
|
||||||
|
interpreter = "cp{version}".format(
|
||||||
|
version=_version_nodot((python_version[0], minor_version))
|
||||||
|
)
|
||||||
|
yield Tag(interpreter, "abi3", platform_)
|
||||||
|
|
||||||
|
|
||||||
|
def _generic_abi() -> List[str]:
|
||||||
|
"""
|
||||||
|
Return the ABI tag based on EXT_SUFFIX.
|
||||||
|
"""
|
||||||
|
# The following are examples of `EXT_SUFFIX`.
|
||||||
|
# We want to keep the parts which are related to the ABI and remove the
|
||||||
|
# parts which are related to the platform:
|
||||||
|
# - linux: '.cpython-310-x86_64-linux-gnu.so' => cp310
|
||||||
|
# - mac: '.cpython-310-darwin.so' => cp310
|
||||||
|
# - win: '.cp310-win_amd64.pyd' => cp310
|
||||||
|
# - win: '.pyd' => cp37 (uses _cpython_abis())
|
||||||
|
# - pypy: '.pypy38-pp73-x86_64-linux-gnu.so' => pypy38_pp73
|
||||||
|
# - graalpy: '.graalpy-38-native-x86_64-darwin.dylib'
|
||||||
|
# => graalpy_38_native
|
||||||
|
|
||||||
|
ext_suffix = _get_config_var("EXT_SUFFIX", warn=True)
|
||||||
|
if not isinstance(ext_suffix, str) or ext_suffix[0] != ".":
|
||||||
|
raise SystemError("invalid sysconfig.get_config_var('EXT_SUFFIX')")
|
||||||
|
parts = ext_suffix.split(".")
|
||||||
|
if len(parts) < 3:
|
||||||
|
# CPython3.7 and earlier uses ".pyd" on Windows.
|
||||||
|
return _cpython_abis(sys.version_info[:2])
|
||||||
|
soabi = parts[1]
|
||||||
|
if soabi.startswith("cpython"):
|
||||||
|
# non-windows
|
||||||
|
abi = "cp" + soabi.split("-")[1]
|
||||||
|
elif soabi.startswith("cp"):
|
||||||
|
# windows
|
||||||
|
abi = soabi.split("-")[0]
|
||||||
|
elif soabi.startswith("pypy"):
|
||||||
|
abi = "-".join(soabi.split("-")[:2])
|
||||||
|
elif soabi.startswith("graalpy"):
|
||||||
|
abi = "-".join(soabi.split("-")[:3])
|
||||||
|
elif soabi:
|
||||||
|
# pyston, ironpython, others?
|
||||||
|
abi = soabi
|
||||||
|
else:
|
||||||
|
return []
|
||||||
|
return [_normalize_string(abi)]
|
||||||
|
|
||||||
|
|
||||||
|
def generic_tags(
|
||||||
|
interpreter: Optional[str] = None,
|
||||||
|
abis: Optional[Iterable[str]] = None,
|
||||||
|
platforms: Optional[Iterable[str]] = None,
|
||||||
|
*,
|
||||||
|
warn: bool = False,
|
||||||
|
) -> Iterator[Tag]:
|
||||||
|
"""
|
||||||
|
Yields the tags for a generic interpreter.
|
||||||
|
|
||||||
|
The tags consist of:
|
||||||
|
- <interpreter>-<abi>-<platform>
|
||||||
|
|
||||||
|
The "none" ABI will be added if it was not explicitly provided.
|
||||||
|
"""
|
||||||
|
if not interpreter:
|
||||||
|
interp_name = interpreter_name()
|
||||||
|
interp_version = interpreter_version(warn=warn)
|
||||||
|
interpreter = "".join([interp_name, interp_version])
|
||||||
|
if abis is None:
|
||||||
|
abis = _generic_abi()
|
||||||
|
else:
|
||||||
|
abis = list(abis)
|
||||||
|
platforms = list(platforms or platform_tags())
|
||||||
|
if "none" not in abis:
|
||||||
|
abis.append("none")
|
||||||
|
for abi in abis:
|
||||||
|
for platform_ in platforms:
|
||||||
|
yield Tag(interpreter, abi, platform_)
|
||||||
|
|
||||||
|
|
||||||
|
def _py_interpreter_range(py_version: PythonVersion) -> Iterator[str]:
|
||||||
|
"""
|
||||||
|
Yields Python versions in descending order.
|
||||||
|
|
||||||
|
After the latest version, the major-only version will be yielded, and then
|
||||||
|
all previous versions of that major version.
|
||||||
|
"""
|
||||||
|
if len(py_version) > 1:
|
||||||
|
yield f"py{_version_nodot(py_version[:2])}"
|
||||||
|
yield f"py{py_version[0]}"
|
||||||
|
if len(py_version) > 1:
|
||||||
|
for minor in range(py_version[1] - 1, -1, -1):
|
||||||
|
yield f"py{_version_nodot((py_version[0], minor))}"
|
||||||
|
|
||||||
|
|
||||||
|
def compatible_tags(
|
||||||
|
python_version: Optional[PythonVersion] = None,
|
||||||
|
interpreter: Optional[str] = None,
|
||||||
|
platforms: Optional[Iterable[str]] = None,
|
||||||
|
) -> Iterator[Tag]:
|
||||||
|
"""
|
||||||
|
Yields the sequence of tags that are compatible with a specific version of Python.
|
||||||
|
|
||||||
|
The tags consist of:
|
||||||
|
- py*-none-<platform>
|
||||||
|
- <interpreter>-none-any # ... if `interpreter` is provided.
|
||||||
|
- py*-none-any
|
||||||
|
"""
|
||||||
|
if not python_version:
|
||||||
|
python_version = sys.version_info[:2]
|
||||||
|
platforms = list(platforms or platform_tags())
|
||||||
|
for version in _py_interpreter_range(python_version):
|
||||||
|
for platform_ in platforms:
|
||||||
|
yield Tag(version, "none", platform_)
|
||||||
|
if interpreter:
|
||||||
|
yield Tag(interpreter, "none", "any")
|
||||||
|
for version in _py_interpreter_range(python_version):
|
||||||
|
yield Tag(version, "none", "any")
|
||||||
|
|
||||||
|
|
||||||
|
def _mac_arch(arch: str, is_32bit: bool = _32_BIT_INTERPRETER) -> str:
|
||||||
|
if not is_32bit:
|
||||||
|
return arch
|
||||||
|
|
||||||
|
if arch.startswith("ppc"):
|
||||||
|
return "ppc"
|
||||||
|
|
||||||
|
return "i386"
|
||||||
|
|
||||||
|
|
||||||
|
def _mac_binary_formats(version: MacVersion, cpu_arch: str) -> List[str]:
|
||||||
|
formats = [cpu_arch]
|
||||||
|
if cpu_arch == "x86_64":
|
||||||
|
if version < (10, 4):
|
||||||
|
return []
|
||||||
|
formats.extend(["intel", "fat64", "fat32"])
|
||||||
|
|
||||||
|
elif cpu_arch == "i386":
|
||||||
|
if version < (10, 4):
|
||||||
|
return []
|
||||||
|
formats.extend(["intel", "fat32", "fat"])
|
||||||
|
|
||||||
|
elif cpu_arch == "ppc64":
|
||||||
|
# TODO: Need to care about 32-bit PPC for ppc64 through 10.2?
|
||||||
|
if version > (10, 5) or version < (10, 4):
|
||||||
|
return []
|
||||||
|
formats.append("fat64")
|
||||||
|
|
||||||
|
elif cpu_arch == "ppc":
|
||||||
|
if version > (10, 6):
|
||||||
|
return []
|
||||||
|
formats.extend(["fat32", "fat"])
|
||||||
|
|
||||||
|
if cpu_arch in {"arm64", "x86_64"}:
|
||||||
|
formats.append("universal2")
|
||||||
|
|
||||||
|
if cpu_arch in {"x86_64", "i386", "ppc64", "ppc", "intel"}:
|
||||||
|
formats.append("universal")
|
||||||
|
|
||||||
|
return formats
|
||||||
|
|
||||||
|
|
||||||
|
def mac_platforms(
|
||||||
|
version: Optional[MacVersion] = None, arch: Optional[str] = None
|
||||||
|
) -> Iterator[str]:
|
||||||
|
"""
|
||||||
|
Yields the platform tags for a macOS system.
|
||||||
|
|
||||||
|
The `version` parameter is a two-item tuple specifying the macOS version to
|
||||||
|
generate platform tags for. The `arch` parameter is the CPU architecture to
|
||||||
|
generate platform tags for. Both parameters default to the appropriate value
|
||||||
|
for the current system.
|
||||||
|
"""
|
||||||
|
version_str, _, cpu_arch = platform.mac_ver()
|
||||||
|
if version is None:
|
||||||
|
version = cast("MacVersion", tuple(map(int, version_str.split(".")[:2])))
|
||||||
|
if version == (10, 16):
|
||||||
|
# When built against an older macOS SDK, Python will report macOS 10.16
|
||||||
|
# instead of the real version.
|
||||||
|
version_str = subprocess.run(
|
||||||
|
[
|
||||||
|
sys.executable,
|
||||||
|
"-sS",
|
||||||
|
"-c",
|
||||||
|
"import platform; print(platform.mac_ver()[0])",
|
||||||
|
],
|
||||||
|
check=True,
|
||||||
|
env={"SYSTEM_VERSION_COMPAT": "0"},
|
||||||
|
stdout=subprocess.PIPE,
|
||||||
|
text=True,
|
||||||
|
).stdout
|
||||||
|
version = cast("MacVersion", tuple(map(int, version_str.split(".")[:2])))
|
||||||
|
else:
|
||||||
|
version = version
|
||||||
|
if arch is None:
|
||||||
|
arch = _mac_arch(cpu_arch)
|
||||||
|
else:
|
||||||
|
arch = arch
|
||||||
|
|
||||||
|
if (10, 0) <= version and version < (11, 0):
|
||||||
|
# Prior to Mac OS 11, each yearly release of Mac OS bumped the
|
||||||
|
# "minor" version number. The major version was always 10.
|
||||||
|
for minor_version in range(version[1], -1, -1):
|
||||||
|
compat_version = 10, minor_version
|
||||||
|
binary_formats = _mac_binary_formats(compat_version, arch)
|
||||||
|
for binary_format in binary_formats:
|
||||||
|
yield "macosx_{major}_{minor}_{binary_format}".format(
|
||||||
|
major=10, minor=minor_version, binary_format=binary_format
|
||||||
|
)
|
||||||
|
|
||||||
|
if version >= (11, 0):
|
||||||
|
# Starting with Mac OS 11, each yearly release bumps the major version
|
||||||
|
# number. The minor versions are now the midyear updates.
|
||||||
|
for major_version in range(version[0], 10, -1):
|
||||||
|
compat_version = major_version, 0
|
||||||
|
binary_formats = _mac_binary_formats(compat_version, arch)
|
||||||
|
for binary_format in binary_formats:
|
||||||
|
yield "macosx_{major}_{minor}_{binary_format}".format(
|
||||||
|
major=major_version, minor=0, binary_format=binary_format
|
||||||
|
)
|
||||||
|
|
||||||
|
if version >= (11, 0):
|
||||||
|
# Mac OS 11 on x86_64 is compatible with binaries from previous releases.
|
||||||
|
# Arm64 support was introduced in 11.0, so no Arm binaries from previous
|
||||||
|
# releases exist.
|
||||||
|
#
|
||||||
|
# However, the "universal2" binary format can have a
|
||||||
|
# macOS version earlier than 11.0 when the x86_64 part of the binary supports
|
||||||
|
# that version of macOS.
|
||||||
|
if arch == "x86_64":
|
||||||
|
for minor_version in range(16, 3, -1):
|
||||||
|
compat_version = 10, minor_version
|
||||||
|
binary_formats = _mac_binary_formats(compat_version, arch)
|
||||||
|
for binary_format in binary_formats:
|
||||||
|
yield "macosx_{major}_{minor}_{binary_format}".format(
|
||||||
|
major=compat_version[0],
|
||||||
|
minor=compat_version[1],
|
||||||
|
binary_format=binary_format,
|
||||||
|
)
|
||||||
|
else:
|
||||||
|
for minor_version in range(16, 3, -1):
|
||||||
|
compat_version = 10, minor_version
|
||||||
|
binary_format = "universal2"
|
||||||
|
yield "macosx_{major}_{minor}_{binary_format}".format(
|
||||||
|
major=compat_version[0],
|
||||||
|
minor=compat_version[1],
|
||||||
|
binary_format=binary_format,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def _linux_platforms(is_32bit: bool = _32_BIT_INTERPRETER) -> Iterator[str]:
|
||||||
|
linux = _normalize_string(sysconfig.get_platform())
|
||||||
|
if not linux.startswith("linux_"):
|
||||||
|
# we should never be here, just yield the sysconfig one and return
|
||||||
|
yield linux
|
||||||
|
return
|
||||||
|
if is_32bit:
|
||||||
|
if linux == "linux_x86_64":
|
||||||
|
linux = "linux_i686"
|
||||||
|
elif linux == "linux_aarch64":
|
||||||
|
linux = "linux_armv8l"
|
||||||
|
_, arch = linux.split("_", 1)
|
||||||
|
archs = {"armv8l": ["armv8l", "armv7l"]}.get(arch, [arch])
|
||||||
|
yield from _manylinux.platform_tags(archs)
|
||||||
|
yield from _musllinux.platform_tags(archs)
|
||||||
|
for arch in archs:
|
||||||
|
yield f"linux_{arch}"
|
||||||
|
|
||||||
|
|
||||||
|
def _generic_platforms() -> Iterator[str]:
|
||||||
|
yield _normalize_string(sysconfig.get_platform())
|
||||||
|
|
||||||
|
|
||||||
|
def platform_tags() -> Iterator[str]:
|
||||||
|
"""
|
||||||
|
Provides the platform tags for this installation.
|
||||||
|
"""
|
||||||
|
if platform.system() == "Darwin":
|
||||||
|
return mac_platforms()
|
||||||
|
elif platform.system() == "Linux":
|
||||||
|
return _linux_platforms()
|
||||||
|
else:
|
||||||
|
return _generic_platforms()
|
||||||
|
|
||||||
|
|
||||||
|
def interpreter_name() -> str:
|
||||||
|
"""
|
||||||
|
Returns the name of the running interpreter.
|
||||||
|
|
||||||
|
Some implementations have a reserved, two-letter abbreviation which will
|
||||||
|
be returned when appropriate.
|
||||||
|
"""
|
||||||
|
name = sys.implementation.name
|
||||||
|
return INTERPRETER_SHORT_NAMES.get(name) or name
|
||||||
|
|
||||||
|
|
||||||
|
def interpreter_version(*, warn: bool = False) -> str:
|
||||||
|
"""
|
||||||
|
Returns the version of the running interpreter.
|
||||||
|
"""
|
||||||
|
version = _get_config_var("py_version_nodot", warn=warn)
|
||||||
|
if version:
|
||||||
|
version = str(version)
|
||||||
|
else:
|
||||||
|
version = _version_nodot(sys.version_info[:2])
|
||||||
|
return version
|
||||||
|
|
||||||
|
|
||||||
|
def _version_nodot(version: PythonVersion) -> str:
|
||||||
|
return "".join(map(str, version))
|
||||||
|
|
||||||
|
|
||||||
|
def sys_tags(*, warn: bool = False) -> Iterator[Tag]:
|
||||||
|
"""
|
||||||
|
Returns the sequence of tag triples for the running interpreter.
|
||||||
|
|
||||||
|
The order of the sequence corresponds to priority order for the
|
||||||
|
interpreter, from most to least important.
|
||||||
|
"""
|
||||||
|
|
||||||
|
interp_name = interpreter_name()
|
||||||
|
if interp_name == "cp":
|
||||||
|
yield from cpython_tags(warn=warn)
|
||||||
|
else:
|
||||||
|
yield from generic_tags()
|
||||||
|
|
||||||
|
if interp_name == "pp":
|
||||||
|
interp = "pp3"
|
||||||
|
elif interp_name == "cp":
|
||||||
|
interp = "cp" + interpreter_version(warn=warn)
|
||||||
|
else:
|
||||||
|
interp = None
|
||||||
|
yield from compatible_tags(interpreter=interp)
|
||||||
|
|
@ -0,0 +1,172 @@
|
||||||
|
# This file is dual licensed under the terms of the Apache License, Version
|
||||||
|
# 2.0, and the BSD License. See the LICENSE file in the root of this repository
|
||||||
|
# for complete details.
|
||||||
|
|
||||||
|
import re
|
||||||
|
from typing import FrozenSet, NewType, Tuple, Union, cast
|
||||||
|
|
||||||
|
from .tags import Tag, parse_tag
|
||||||
|
from .version import InvalidVersion, Version
|
||||||
|
|
||||||
|
BuildTag = Union[Tuple[()], Tuple[int, str]]
|
||||||
|
NormalizedName = NewType("NormalizedName", str)
|
||||||
|
|
||||||
|
|
||||||
|
class InvalidName(ValueError):
|
||||||
|
"""
|
||||||
|
An invalid distribution name; users should refer to the packaging user guide.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class InvalidWheelFilename(ValueError):
|
||||||
|
"""
|
||||||
|
An invalid wheel filename was found, users should refer to PEP 427.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class InvalidSdistFilename(ValueError):
|
||||||
|
"""
|
||||||
|
An invalid sdist filename was found, users should refer to the packaging user guide.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
# Core metadata spec for `Name`
|
||||||
|
_validate_regex = re.compile(
|
||||||
|
r"^([A-Z0-9]|[A-Z0-9][A-Z0-9._-]*[A-Z0-9])$", re.IGNORECASE
|
||||||
|
)
|
||||||
|
_canonicalize_regex = re.compile(r"[-_.]+")
|
||||||
|
_normalized_regex = re.compile(r"^([a-z0-9]|[a-z0-9]([a-z0-9-](?!--))*[a-z0-9])$")
|
||||||
|
# PEP 427: The build number must start with a digit.
|
||||||
|
_build_tag_regex = re.compile(r"(\d+)(.*)")
|
||||||
|
|
||||||
|
|
||||||
|
def canonicalize_name(name: str, *, validate: bool = False) -> NormalizedName:
|
||||||
|
if validate and not _validate_regex.match(name):
|
||||||
|
raise InvalidName(f"name is invalid: {name!r}")
|
||||||
|
# This is taken from PEP 503.
|
||||||
|
value = _canonicalize_regex.sub("-", name).lower()
|
||||||
|
return cast(NormalizedName, value)
|
||||||
|
|
||||||
|
|
||||||
|
def is_normalized_name(name: str) -> bool:
|
||||||
|
return _normalized_regex.match(name) is not None
|
||||||
|
|
||||||
|
|
||||||
|
def canonicalize_version(
|
||||||
|
version: Union[Version, str], *, strip_trailing_zero: bool = True
|
||||||
|
) -> str:
|
||||||
|
"""
|
||||||
|
This is very similar to Version.__str__, but has one subtle difference
|
||||||
|
with the way it handles the release segment.
|
||||||
|
"""
|
||||||
|
if isinstance(version, str):
|
||||||
|
try:
|
||||||
|
parsed = Version(version)
|
||||||
|
except InvalidVersion:
|
||||||
|
# Legacy versions cannot be normalized
|
||||||
|
return version
|
||||||
|
else:
|
||||||
|
parsed = version
|
||||||
|
|
||||||
|
parts = []
|
||||||
|
|
||||||
|
# Epoch
|
||||||
|
if parsed.epoch != 0:
|
||||||
|
parts.append(f"{parsed.epoch}!")
|
||||||
|
|
||||||
|
# Release segment
|
||||||
|
release_segment = ".".join(str(x) for x in parsed.release)
|
||||||
|
if strip_trailing_zero:
|
||||||
|
# NB: This strips trailing '.0's to normalize
|
||||||
|
release_segment = re.sub(r"(\.0)+$", "", release_segment)
|
||||||
|
parts.append(release_segment)
|
||||||
|
|
||||||
|
# Pre-release
|
||||||
|
if parsed.pre is not None:
|
||||||
|
parts.append("".join(str(x) for x in parsed.pre))
|
||||||
|
|
||||||
|
# Post-release
|
||||||
|
if parsed.post is not None:
|
||||||
|
parts.append(f".post{parsed.post}")
|
||||||
|
|
||||||
|
# Development release
|
||||||
|
if parsed.dev is not None:
|
||||||
|
parts.append(f".dev{parsed.dev}")
|
||||||
|
|
||||||
|
# Local version segment
|
||||||
|
if parsed.local is not None:
|
||||||
|
parts.append(f"+{parsed.local}")
|
||||||
|
|
||||||
|
return "".join(parts)
|
||||||
|
|
||||||
|
|
||||||
|
def parse_wheel_filename(
|
||||||
|
filename: str,
|
||||||
|
) -> Tuple[NormalizedName, Version, BuildTag, FrozenSet[Tag]]:
|
||||||
|
if not filename.endswith(".whl"):
|
||||||
|
raise InvalidWheelFilename(
|
||||||
|
f"Invalid wheel filename (extension must be '.whl'): {filename}"
|
||||||
|
)
|
||||||
|
|
||||||
|
filename = filename[:-4]
|
||||||
|
dashes = filename.count("-")
|
||||||
|
if dashes not in (4, 5):
|
||||||
|
raise InvalidWheelFilename(
|
||||||
|
f"Invalid wheel filename (wrong number of parts): {filename}"
|
||||||
|
)
|
||||||
|
|
||||||
|
parts = filename.split("-", dashes - 2)
|
||||||
|
name_part = parts[0]
|
||||||
|
# See PEP 427 for the rules on escaping the project name.
|
||||||
|
if "__" in name_part or re.match(r"^[\w\d._]*$", name_part, re.UNICODE) is None:
|
||||||
|
raise InvalidWheelFilename(f"Invalid project name: {filename}")
|
||||||
|
name = canonicalize_name(name_part)
|
||||||
|
|
||||||
|
try:
|
||||||
|
version = Version(parts[1])
|
||||||
|
except InvalidVersion as e:
|
||||||
|
raise InvalidWheelFilename(
|
||||||
|
f"Invalid wheel filename (invalid version): {filename}"
|
||||||
|
) from e
|
||||||
|
|
||||||
|
if dashes == 5:
|
||||||
|
build_part = parts[2]
|
||||||
|
build_match = _build_tag_regex.match(build_part)
|
||||||
|
if build_match is None:
|
||||||
|
raise InvalidWheelFilename(
|
||||||
|
f"Invalid build number: {build_part} in '{filename}'"
|
||||||
|
)
|
||||||
|
build = cast(BuildTag, (int(build_match.group(1)), build_match.group(2)))
|
||||||
|
else:
|
||||||
|
build = ()
|
||||||
|
tags = parse_tag(parts[-1])
|
||||||
|
return (name, version, build, tags)
|
||||||
|
|
||||||
|
|
||||||
|
def parse_sdist_filename(filename: str) -> Tuple[NormalizedName, Version]:
|
||||||
|
if filename.endswith(".tar.gz"):
|
||||||
|
file_stem = filename[: -len(".tar.gz")]
|
||||||
|
elif filename.endswith(".zip"):
|
||||||
|
file_stem = filename[: -len(".zip")]
|
||||||
|
else:
|
||||||
|
raise InvalidSdistFilename(
|
||||||
|
f"Invalid sdist filename (extension must be '.tar.gz' or '.zip'):"
|
||||||
|
f" {filename}"
|
||||||
|
)
|
||||||
|
|
||||||
|
# We are requiring a PEP 440 version, which cannot contain dashes,
|
||||||
|
# so we split on the last dash.
|
||||||
|
name_part, sep, version_part = file_stem.rpartition("-")
|
||||||
|
if not sep:
|
||||||
|
raise InvalidSdistFilename(f"Invalid sdist filename: {filename}")
|
||||||
|
|
||||||
|
name = canonicalize_name(name_part)
|
||||||
|
|
||||||
|
try:
|
||||||
|
version = Version(version_part)
|
||||||
|
except InvalidVersion as e:
|
||||||
|
raise InvalidSdistFilename(
|
||||||
|
f"Invalid sdist filename (invalid version): {filename}"
|
||||||
|
) from e
|
||||||
|
|
||||||
|
return (name, version)
|
||||||
|
|
@ -0,0 +1,563 @@
|
||||||
|
# This file is dual licensed under the terms of the Apache License, Version
|
||||||
|
# 2.0, and the BSD License. See the LICENSE file in the root of this repository
|
||||||
|
# for complete details.
|
||||||
|
"""
|
||||||
|
.. testsetup::
|
||||||
|
|
||||||
|
from packaging.version import parse, Version
|
||||||
|
"""
|
||||||
|
|
||||||
|
import itertools
|
||||||
|
import re
|
||||||
|
from typing import Any, Callable, NamedTuple, Optional, SupportsInt, Tuple, Union
|
||||||
|
|
||||||
|
from ._structures import Infinity, InfinityType, NegativeInfinity, NegativeInfinityType
|
||||||
|
|
||||||
|
__all__ = ["VERSION_PATTERN", "parse", "Version", "InvalidVersion"]
|
||||||
|
|
||||||
|
LocalType = Tuple[Union[int, str], ...]
|
||||||
|
|
||||||
|
CmpPrePostDevType = Union[InfinityType, NegativeInfinityType, Tuple[str, int]]
|
||||||
|
CmpLocalType = Union[
|
||||||
|
NegativeInfinityType,
|
||||||
|
Tuple[Union[Tuple[int, str], Tuple[NegativeInfinityType, Union[int, str]]], ...],
|
||||||
|
]
|
||||||
|
CmpKey = Tuple[
|
||||||
|
int,
|
||||||
|
Tuple[int, ...],
|
||||||
|
CmpPrePostDevType,
|
||||||
|
CmpPrePostDevType,
|
||||||
|
CmpPrePostDevType,
|
||||||
|
CmpLocalType,
|
||||||
|
]
|
||||||
|
VersionComparisonMethod = Callable[[CmpKey, CmpKey], bool]
|
||||||
|
|
||||||
|
|
||||||
|
class _Version(NamedTuple):
|
||||||
|
epoch: int
|
||||||
|
release: Tuple[int, ...]
|
||||||
|
dev: Optional[Tuple[str, int]]
|
||||||
|
pre: Optional[Tuple[str, int]]
|
||||||
|
post: Optional[Tuple[str, int]]
|
||||||
|
local: Optional[LocalType]
|
||||||
|
|
||||||
|
|
||||||
|
def parse(version: str) -> "Version":
|
||||||
|
"""Parse the given version string.
|
||||||
|
|
||||||
|
>>> parse('1.0.dev1')
|
||||||
|
<Version('1.0.dev1')>
|
||||||
|
|
||||||
|
:param version: The version string to parse.
|
||||||
|
:raises InvalidVersion: When the version string is not a valid version.
|
||||||
|
"""
|
||||||
|
return Version(version)
|
||||||
|
|
||||||
|
|
||||||
|
class InvalidVersion(ValueError):
|
||||||
|
"""Raised when a version string is not a valid version.
|
||||||
|
|
||||||
|
>>> Version("invalid")
|
||||||
|
Traceback (most recent call last):
|
||||||
|
...
|
||||||
|
packaging.version.InvalidVersion: Invalid version: 'invalid'
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class _BaseVersion:
|
||||||
|
_key: Tuple[Any, ...]
|
||||||
|
|
||||||
|
def __hash__(self) -> int:
|
||||||
|
return hash(self._key)
|
||||||
|
|
||||||
|
# Please keep the duplicated `isinstance` check
|
||||||
|
# in the six comparisons hereunder
|
||||||
|
# unless you find a way to avoid adding overhead function calls.
|
||||||
|
def __lt__(self, other: "_BaseVersion") -> bool:
|
||||||
|
if not isinstance(other, _BaseVersion):
|
||||||
|
return NotImplemented
|
||||||
|
|
||||||
|
return self._key < other._key
|
||||||
|
|
||||||
|
def __le__(self, other: "_BaseVersion") -> bool:
|
||||||
|
if not isinstance(other, _BaseVersion):
|
||||||
|
return NotImplemented
|
||||||
|
|
||||||
|
return self._key <= other._key
|
||||||
|
|
||||||
|
def __eq__(self, other: object) -> bool:
|
||||||
|
if not isinstance(other, _BaseVersion):
|
||||||
|
return NotImplemented
|
||||||
|
|
||||||
|
return self._key == other._key
|
||||||
|
|
||||||
|
def __ge__(self, other: "_BaseVersion") -> bool:
|
||||||
|
if not isinstance(other, _BaseVersion):
|
||||||
|
return NotImplemented
|
||||||
|
|
||||||
|
return self._key >= other._key
|
||||||
|
|
||||||
|
def __gt__(self, other: "_BaseVersion") -> bool:
|
||||||
|
if not isinstance(other, _BaseVersion):
|
||||||
|
return NotImplemented
|
||||||
|
|
||||||
|
return self._key > other._key
|
||||||
|
|
||||||
|
def __ne__(self, other: object) -> bool:
|
||||||
|
if not isinstance(other, _BaseVersion):
|
||||||
|
return NotImplemented
|
||||||
|
|
||||||
|
return self._key != other._key
|
||||||
|
|
||||||
|
|
||||||
|
# Deliberately not anchored to the start and end of the string, to make it
|
||||||
|
# easier for 3rd party code to reuse
|
||||||
|
_VERSION_PATTERN = r"""
|
||||||
|
v?
|
||||||
|
(?:
|
||||||
|
(?:(?P<epoch>[0-9]+)!)? # epoch
|
||||||
|
(?P<release>[0-9]+(?:\.[0-9]+)*) # release segment
|
||||||
|
(?P<pre> # pre-release
|
||||||
|
[-_\.]?
|
||||||
|
(?P<pre_l>alpha|a|beta|b|preview|pre|c|rc)
|
||||||
|
[-_\.]?
|
||||||
|
(?P<pre_n>[0-9]+)?
|
||||||
|
)?
|
||||||
|
(?P<post> # post release
|
||||||
|
(?:-(?P<post_n1>[0-9]+))
|
||||||
|
|
|
||||||
|
(?:
|
||||||
|
[-_\.]?
|
||||||
|
(?P<post_l>post|rev|r)
|
||||||
|
[-_\.]?
|
||||||
|
(?P<post_n2>[0-9]+)?
|
||||||
|
)
|
||||||
|
)?
|
||||||
|
(?P<dev> # dev release
|
||||||
|
[-_\.]?
|
||||||
|
(?P<dev_l>dev)
|
||||||
|
[-_\.]?
|
||||||
|
(?P<dev_n>[0-9]+)?
|
||||||
|
)?
|
||||||
|
)
|
||||||
|
(?:\+(?P<local>[a-z0-9]+(?:[-_\.][a-z0-9]+)*))? # local version
|
||||||
|
"""
|
||||||
|
|
||||||
|
VERSION_PATTERN = _VERSION_PATTERN
|
||||||
|
"""
|
||||||
|
A string containing the regular expression used to match a valid version.
|
||||||
|
|
||||||
|
The pattern is not anchored at either end, and is intended for embedding in larger
|
||||||
|
expressions (for example, matching a version number as part of a file name). The
|
||||||
|
regular expression should be compiled with the ``re.VERBOSE`` and ``re.IGNORECASE``
|
||||||
|
flags set.
|
||||||
|
|
||||||
|
:meta hide-value:
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
class Version(_BaseVersion):
|
||||||
|
"""This class abstracts handling of a project's versions.
|
||||||
|
|
||||||
|
A :class:`Version` instance is comparison aware and can be compared and
|
||||||
|
sorted using the standard Python interfaces.
|
||||||
|
|
||||||
|
>>> v1 = Version("1.0a5")
|
||||||
|
>>> v2 = Version("1.0")
|
||||||
|
>>> v1
|
||||||
|
<Version('1.0a5')>
|
||||||
|
>>> v2
|
||||||
|
<Version('1.0')>
|
||||||
|
>>> v1 < v2
|
||||||
|
True
|
||||||
|
>>> v1 == v2
|
||||||
|
False
|
||||||
|
>>> v1 > v2
|
||||||
|
False
|
||||||
|
>>> v1 >= v2
|
||||||
|
False
|
||||||
|
>>> v1 <= v2
|
||||||
|
True
|
||||||
|
"""
|
||||||
|
|
||||||
|
_regex = re.compile(r"^\s*" + VERSION_PATTERN + r"\s*$", re.VERBOSE | re.IGNORECASE)
|
||||||
|
_key: CmpKey
|
||||||
|
|
||||||
|
def __init__(self, version: str) -> None:
|
||||||
|
"""Initialize a Version object.
|
||||||
|
|
||||||
|
:param version:
|
||||||
|
The string representation of a version which will be parsed and normalized
|
||||||
|
before use.
|
||||||
|
:raises InvalidVersion:
|
||||||
|
If the ``version`` does not conform to PEP 440 in any way then this
|
||||||
|
exception will be raised.
|
||||||
|
"""
|
||||||
|
|
||||||
|
# Validate the version and parse it into pieces
|
||||||
|
match = self._regex.search(version)
|
||||||
|
if not match:
|
||||||
|
raise InvalidVersion(f"Invalid version: '{version}'")
|
||||||
|
|
||||||
|
# Store the parsed out pieces of the version
|
||||||
|
self._version = _Version(
|
||||||
|
epoch=int(match.group("epoch")) if match.group("epoch") else 0,
|
||||||
|
release=tuple(int(i) for i in match.group("release").split(".")),
|
||||||
|
pre=_parse_letter_version(match.group("pre_l"), match.group("pre_n")),
|
||||||
|
post=_parse_letter_version(
|
||||||
|
match.group("post_l"), match.group("post_n1") or match.group("post_n2")
|
||||||
|
),
|
||||||
|
dev=_parse_letter_version(match.group("dev_l"), match.group("dev_n")),
|
||||||
|
local=_parse_local_version(match.group("local")),
|
||||||
|
)
|
||||||
|
|
||||||
|
# Generate a key which will be used for sorting
|
||||||
|
self._key = _cmpkey(
|
||||||
|
self._version.epoch,
|
||||||
|
self._version.release,
|
||||||
|
self._version.pre,
|
||||||
|
self._version.post,
|
||||||
|
self._version.dev,
|
||||||
|
self._version.local,
|
||||||
|
)
|
||||||
|
|
||||||
|
def __repr__(self) -> str:
|
||||||
|
"""A representation of the Version that shows all internal state.
|
||||||
|
|
||||||
|
>>> Version('1.0.0')
|
||||||
|
<Version('1.0.0')>
|
||||||
|
"""
|
||||||
|
return f"<Version('{self}')>"
|
||||||
|
|
||||||
|
def __str__(self) -> str:
|
||||||
|
"""A string representation of the version that can be rounded-tripped.
|
||||||
|
|
||||||
|
>>> str(Version("1.0a5"))
|
||||||
|
'1.0a5'
|
||||||
|
"""
|
||||||
|
parts = []
|
||||||
|
|
||||||
|
# Epoch
|
||||||
|
if self.epoch != 0:
|
||||||
|
parts.append(f"{self.epoch}!")
|
||||||
|
|
||||||
|
# Release segment
|
||||||
|
parts.append(".".join(str(x) for x in self.release))
|
||||||
|
|
||||||
|
# Pre-release
|
||||||
|
if self.pre is not None:
|
||||||
|
parts.append("".join(str(x) for x in self.pre))
|
||||||
|
|
||||||
|
# Post-release
|
||||||
|
if self.post is not None:
|
||||||
|
parts.append(f".post{self.post}")
|
||||||
|
|
||||||
|
# Development release
|
||||||
|
if self.dev is not None:
|
||||||
|
parts.append(f".dev{self.dev}")
|
||||||
|
|
||||||
|
# Local version segment
|
||||||
|
if self.local is not None:
|
||||||
|
parts.append(f"+{self.local}")
|
||||||
|
|
||||||
|
return "".join(parts)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def epoch(self) -> int:
|
||||||
|
"""The epoch of the version.
|
||||||
|
|
||||||
|
>>> Version("2.0.0").epoch
|
||||||
|
0
|
||||||
|
>>> Version("1!2.0.0").epoch
|
||||||
|
1
|
||||||
|
"""
|
||||||
|
return self._version.epoch
|
||||||
|
|
||||||
|
@property
|
||||||
|
def release(self) -> Tuple[int, ...]:
|
||||||
|
"""The components of the "release" segment of the version.
|
||||||
|
|
||||||
|
>>> Version("1.2.3").release
|
||||||
|
(1, 2, 3)
|
||||||
|
>>> Version("2.0.0").release
|
||||||
|
(2, 0, 0)
|
||||||
|
>>> Version("1!2.0.0.post0").release
|
||||||
|
(2, 0, 0)
|
||||||
|
|
||||||
|
Includes trailing zeroes but not the epoch or any pre-release / development /
|
||||||
|
post-release suffixes.
|
||||||
|
"""
|
||||||
|
return self._version.release
|
||||||
|
|
||||||
|
@property
|
||||||
|
def pre(self) -> Optional[Tuple[str, int]]:
|
||||||
|
"""The pre-release segment of the version.
|
||||||
|
|
||||||
|
>>> print(Version("1.2.3").pre)
|
||||||
|
None
|
||||||
|
>>> Version("1.2.3a1").pre
|
||||||
|
('a', 1)
|
||||||
|
>>> Version("1.2.3b1").pre
|
||||||
|
('b', 1)
|
||||||
|
>>> Version("1.2.3rc1").pre
|
||||||
|
('rc', 1)
|
||||||
|
"""
|
||||||
|
return self._version.pre
|
||||||
|
|
||||||
|
@property
|
||||||
|
def post(self) -> Optional[int]:
|
||||||
|
"""The post-release number of the version.
|
||||||
|
|
||||||
|
>>> print(Version("1.2.3").post)
|
||||||
|
None
|
||||||
|
>>> Version("1.2.3.post1").post
|
||||||
|
1
|
||||||
|
"""
|
||||||
|
return self._version.post[1] if self._version.post else None
|
||||||
|
|
||||||
|
@property
|
||||||
|
def dev(self) -> Optional[int]:
|
||||||
|
"""The development number of the version.
|
||||||
|
|
||||||
|
>>> print(Version("1.2.3").dev)
|
||||||
|
None
|
||||||
|
>>> Version("1.2.3.dev1").dev
|
||||||
|
1
|
||||||
|
"""
|
||||||
|
return self._version.dev[1] if self._version.dev else None
|
||||||
|
|
||||||
|
@property
|
||||||
|
def local(self) -> Optional[str]:
|
||||||
|
"""The local version segment of the version.
|
||||||
|
|
||||||
|
>>> print(Version("1.2.3").local)
|
||||||
|
None
|
||||||
|
>>> Version("1.2.3+abc").local
|
||||||
|
'abc'
|
||||||
|
"""
|
||||||
|
if self._version.local:
|
||||||
|
return ".".join(str(x) for x in self._version.local)
|
||||||
|
else:
|
||||||
|
return None
|
||||||
|
|
||||||
|
@property
|
||||||
|
def public(self) -> str:
|
||||||
|
"""The public portion of the version.
|
||||||
|
|
||||||
|
>>> Version("1.2.3").public
|
||||||
|
'1.2.3'
|
||||||
|
>>> Version("1.2.3+abc").public
|
||||||
|
'1.2.3'
|
||||||
|
>>> Version("1.2.3+abc.dev1").public
|
||||||
|
'1.2.3'
|
||||||
|
"""
|
||||||
|
return str(self).split("+", 1)[0]
|
||||||
|
|
||||||
|
@property
|
||||||
|
def base_version(self) -> str:
|
||||||
|
"""The "base version" of the version.
|
||||||
|
|
||||||
|
>>> Version("1.2.3").base_version
|
||||||
|
'1.2.3'
|
||||||
|
>>> Version("1.2.3+abc").base_version
|
||||||
|
'1.2.3'
|
||||||
|
>>> Version("1!1.2.3+abc.dev1").base_version
|
||||||
|
'1!1.2.3'
|
||||||
|
|
||||||
|
The "base version" is the public version of the project without any pre or post
|
||||||
|
release markers.
|
||||||
|
"""
|
||||||
|
parts = []
|
||||||
|
|
||||||
|
# Epoch
|
||||||
|
if self.epoch != 0:
|
||||||
|
parts.append(f"{self.epoch}!")
|
||||||
|
|
||||||
|
# Release segment
|
||||||
|
parts.append(".".join(str(x) for x in self.release))
|
||||||
|
|
||||||
|
return "".join(parts)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def is_prerelease(self) -> bool:
|
||||||
|
"""Whether this version is a pre-release.
|
||||||
|
|
||||||
|
>>> Version("1.2.3").is_prerelease
|
||||||
|
False
|
||||||
|
>>> Version("1.2.3a1").is_prerelease
|
||||||
|
True
|
||||||
|
>>> Version("1.2.3b1").is_prerelease
|
||||||
|
True
|
||||||
|
>>> Version("1.2.3rc1").is_prerelease
|
||||||
|
True
|
||||||
|
>>> Version("1.2.3dev1").is_prerelease
|
||||||
|
True
|
||||||
|
"""
|
||||||
|
return self.dev is not None or self.pre is not None
|
||||||
|
|
||||||
|
@property
|
||||||
|
def is_postrelease(self) -> bool:
|
||||||
|
"""Whether this version is a post-release.
|
||||||
|
|
||||||
|
>>> Version("1.2.3").is_postrelease
|
||||||
|
False
|
||||||
|
>>> Version("1.2.3.post1").is_postrelease
|
||||||
|
True
|
||||||
|
"""
|
||||||
|
return self.post is not None
|
||||||
|
|
||||||
|
@property
|
||||||
|
def is_devrelease(self) -> bool:
|
||||||
|
"""Whether this version is a development release.
|
||||||
|
|
||||||
|
>>> Version("1.2.3").is_devrelease
|
||||||
|
False
|
||||||
|
>>> Version("1.2.3.dev1").is_devrelease
|
||||||
|
True
|
||||||
|
"""
|
||||||
|
return self.dev is not None
|
||||||
|
|
||||||
|
@property
|
||||||
|
def major(self) -> int:
|
||||||
|
"""The first item of :attr:`release` or ``0`` if unavailable.
|
||||||
|
|
||||||
|
>>> Version("1.2.3").major
|
||||||
|
1
|
||||||
|
"""
|
||||||
|
return self.release[0] if len(self.release) >= 1 else 0
|
||||||
|
|
||||||
|
@property
|
||||||
|
def minor(self) -> int:
|
||||||
|
"""The second item of :attr:`release` or ``0`` if unavailable.
|
||||||
|
|
||||||
|
>>> Version("1.2.3").minor
|
||||||
|
2
|
||||||
|
>>> Version("1").minor
|
||||||
|
0
|
||||||
|
"""
|
||||||
|
return self.release[1] if len(self.release) >= 2 else 0
|
||||||
|
|
||||||
|
@property
|
||||||
|
def micro(self) -> int:
|
||||||
|
"""The third item of :attr:`release` or ``0`` if unavailable.
|
||||||
|
|
||||||
|
>>> Version("1.2.3").micro
|
||||||
|
3
|
||||||
|
>>> Version("1").micro
|
||||||
|
0
|
||||||
|
"""
|
||||||
|
return self.release[2] if len(self.release) >= 3 else 0
|
||||||
|
|
||||||
|
|
||||||
|
def _parse_letter_version(
|
||||||
|
letter: Optional[str], number: Union[str, bytes, SupportsInt, None]
|
||||||
|
) -> Optional[Tuple[str, int]]:
|
||||||
|
|
||||||
|
if letter:
|
||||||
|
# We consider there to be an implicit 0 in a pre-release if there is
|
||||||
|
# not a numeral associated with it.
|
||||||
|
if number is None:
|
||||||
|
number = 0
|
||||||
|
|
||||||
|
# We normalize any letters to their lower case form
|
||||||
|
letter = letter.lower()
|
||||||
|
|
||||||
|
# We consider some words to be alternate spellings of other words and
|
||||||
|
# in those cases we want to normalize the spellings to our preferred
|
||||||
|
# spelling.
|
||||||
|
if letter == "alpha":
|
||||||
|
letter = "a"
|
||||||
|
elif letter == "beta":
|
||||||
|
letter = "b"
|
||||||
|
elif letter in ["c", "pre", "preview"]:
|
||||||
|
letter = "rc"
|
||||||
|
elif letter in ["rev", "r"]:
|
||||||
|
letter = "post"
|
||||||
|
|
||||||
|
return letter, int(number)
|
||||||
|
if not letter and number:
|
||||||
|
# We assume if we are given a number, but we are not given a letter
|
||||||
|
# then this is using the implicit post release syntax (e.g. 1.0-1)
|
||||||
|
letter = "post"
|
||||||
|
|
||||||
|
return letter, int(number)
|
||||||
|
|
||||||
|
return None
|
||||||
|
|
||||||
|
|
||||||
|
_local_version_separators = re.compile(r"[\._-]")
|
||||||
|
|
||||||
|
|
||||||
|
def _parse_local_version(local: Optional[str]) -> Optional[LocalType]:
|
||||||
|
"""
|
||||||
|
Takes a string like abc.1.twelve and turns it into ("abc", 1, "twelve").
|
||||||
|
"""
|
||||||
|
if local is not None:
|
||||||
|
return tuple(
|
||||||
|
part.lower() if not part.isdigit() else int(part)
|
||||||
|
for part in _local_version_separators.split(local)
|
||||||
|
)
|
||||||
|
return None
|
||||||
|
|
||||||
|
|
||||||
|
def _cmpkey(
|
||||||
|
epoch: int,
|
||||||
|
release: Tuple[int, ...],
|
||||||
|
pre: Optional[Tuple[str, int]],
|
||||||
|
post: Optional[Tuple[str, int]],
|
||||||
|
dev: Optional[Tuple[str, int]],
|
||||||
|
local: Optional[LocalType],
|
||||||
|
) -> CmpKey:
|
||||||
|
|
||||||
|
# When we compare a release version, we want to compare it with all of the
|
||||||
|
# trailing zeros removed. So we'll use a reverse the list, drop all the now
|
||||||
|
# leading zeros until we come to something non zero, then take the rest
|
||||||
|
# re-reverse it back into the correct order and make it a tuple and use
|
||||||
|
# that for our sorting key.
|
||||||
|
_release = tuple(
|
||||||
|
reversed(list(itertools.dropwhile(lambda x: x == 0, reversed(release))))
|
||||||
|
)
|
||||||
|
|
||||||
|
# We need to "trick" the sorting algorithm to put 1.0.dev0 before 1.0a0.
|
||||||
|
# We'll do this by abusing the pre segment, but we _only_ want to do this
|
||||||
|
# if there is not a pre or a post segment. If we have one of those then
|
||||||
|
# the normal sorting rules will handle this case correctly.
|
||||||
|
if pre is None and post is None and dev is not None:
|
||||||
|
_pre: CmpPrePostDevType = NegativeInfinity
|
||||||
|
# Versions without a pre-release (except as noted above) should sort after
|
||||||
|
# those with one.
|
||||||
|
elif pre is None:
|
||||||
|
_pre = Infinity
|
||||||
|
else:
|
||||||
|
_pre = pre
|
||||||
|
|
||||||
|
# Versions without a post segment should sort before those with one.
|
||||||
|
if post is None:
|
||||||
|
_post: CmpPrePostDevType = NegativeInfinity
|
||||||
|
|
||||||
|
else:
|
||||||
|
_post = post
|
||||||
|
|
||||||
|
# Versions without a development segment should sort after those with one.
|
||||||
|
if dev is None:
|
||||||
|
_dev: CmpPrePostDevType = Infinity
|
||||||
|
|
||||||
|
else:
|
||||||
|
_dev = dev
|
||||||
|
|
||||||
|
if local is None:
|
||||||
|
# Versions without a local segment should sort before those with one.
|
||||||
|
_local: CmpLocalType = NegativeInfinity
|
||||||
|
else:
|
||||||
|
# Versions with a local segment need that segment parsed to implement
|
||||||
|
# the sorting rules in PEP440.
|
||||||
|
# - Alpha numeric segments sort before numeric segments
|
||||||
|
# - Alpha numeric segments sort lexicographically
|
||||||
|
# - Numeric segments sort numerically
|
||||||
|
# - Shorter versions sort before longer versions when the prefixes
|
||||||
|
# match exactly
|
||||||
|
_local = tuple(
|
||||||
|
(i, "") if isinstance(i, int) else (NegativeInfinity, i) for i in local
|
||||||
|
)
|
||||||
|
|
||||||
|
return epoch, _release, _pre, _post, _dev, _local
|
||||||
|
|
@ -0,0 +1,342 @@
|
||||||
|
"""
|
||||||
|
Utilities for determining application-specific dirs. See <https://github.com/platformdirs/platformdirs> for details and
|
||||||
|
usage.
|
||||||
|
"""
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import os
|
||||||
|
import sys
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 8): # pragma: no cover (py38+)
|
||||||
|
from typing import Literal
|
||||||
|
else: # pragma: no cover (py38+)
|
||||||
|
from ..typing_extensions import Literal
|
||||||
|
|
||||||
|
from .api import PlatformDirsABC
|
||||||
|
from .version import __version__
|
||||||
|
from .version import __version_tuple__ as __version_info__
|
||||||
|
|
||||||
|
|
||||||
|
def _set_platform_dir_class() -> type[PlatformDirsABC]:
|
||||||
|
if sys.platform == "win32":
|
||||||
|
from .windows import Windows as Result
|
||||||
|
elif sys.platform == "darwin":
|
||||||
|
from .macos import MacOS as Result
|
||||||
|
else:
|
||||||
|
from .unix import Unix as Result
|
||||||
|
|
||||||
|
if os.getenv("ANDROID_DATA") == "/data" and os.getenv("ANDROID_ROOT") == "/system":
|
||||||
|
|
||||||
|
if os.getenv("SHELL") or os.getenv("PREFIX"):
|
||||||
|
return Result
|
||||||
|
|
||||||
|
from .android import _android_folder
|
||||||
|
|
||||||
|
if _android_folder() is not None:
|
||||||
|
from .android import Android
|
||||||
|
|
||||||
|
return Android # return to avoid redefinition of result
|
||||||
|
|
||||||
|
return Result
|
||||||
|
|
||||||
|
|
||||||
|
PlatformDirs = _set_platform_dir_class() #: Currently active platform
|
||||||
|
AppDirs = PlatformDirs #: Backwards compatibility with appdirs
|
||||||
|
|
||||||
|
|
||||||
|
def user_data_dir(
|
||||||
|
appname: str | None = None,
|
||||||
|
appauthor: str | None | Literal[False] = None,
|
||||||
|
version: str | None = None,
|
||||||
|
roaming: bool = False,
|
||||||
|
) -> str:
|
||||||
|
"""
|
||||||
|
:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
|
||||||
|
:param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
|
||||||
|
:param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
:param roaming: See `roaming <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
:returns: data directory tied to the user
|
||||||
|
"""
|
||||||
|
return PlatformDirs(appname=appname, appauthor=appauthor, version=version, roaming=roaming).user_data_dir
|
||||||
|
|
||||||
|
|
||||||
|
def site_data_dir(
|
||||||
|
appname: str | None = None,
|
||||||
|
appauthor: str | None | Literal[False] = None,
|
||||||
|
version: str | None = None,
|
||||||
|
multipath: bool = False,
|
||||||
|
) -> str:
|
||||||
|
"""
|
||||||
|
:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
|
||||||
|
:param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
|
||||||
|
:param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
:param multipath: See `roaming <platformdirs.api.PlatformDirsABC.multipath>`.
|
||||||
|
:returns: data directory shared by users
|
||||||
|
"""
|
||||||
|
return PlatformDirs(appname=appname, appauthor=appauthor, version=version, multipath=multipath).site_data_dir
|
||||||
|
|
||||||
|
|
||||||
|
def user_config_dir(
|
||||||
|
appname: str | None = None,
|
||||||
|
appauthor: str | None | Literal[False] = None,
|
||||||
|
version: str | None = None,
|
||||||
|
roaming: bool = False,
|
||||||
|
) -> str:
|
||||||
|
"""
|
||||||
|
:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
|
||||||
|
:param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
|
||||||
|
:param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
:param roaming: See `roaming <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
:returns: config directory tied to the user
|
||||||
|
"""
|
||||||
|
return PlatformDirs(appname=appname, appauthor=appauthor, version=version, roaming=roaming).user_config_dir
|
||||||
|
|
||||||
|
|
||||||
|
def site_config_dir(
|
||||||
|
appname: str | None = None,
|
||||||
|
appauthor: str | None | Literal[False] = None,
|
||||||
|
version: str | None = None,
|
||||||
|
multipath: bool = False,
|
||||||
|
) -> str:
|
||||||
|
"""
|
||||||
|
:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
|
||||||
|
:param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
|
||||||
|
:param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
:param multipath: See `roaming <platformdirs.api.PlatformDirsABC.multipath>`.
|
||||||
|
:returns: config directory shared by the users
|
||||||
|
"""
|
||||||
|
return PlatformDirs(appname=appname, appauthor=appauthor, version=version, multipath=multipath).site_config_dir
|
||||||
|
|
||||||
|
|
||||||
|
def user_cache_dir(
|
||||||
|
appname: str | None = None,
|
||||||
|
appauthor: str | None | Literal[False] = None,
|
||||||
|
version: str | None = None,
|
||||||
|
opinion: bool = True,
|
||||||
|
) -> str:
|
||||||
|
"""
|
||||||
|
:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
|
||||||
|
:param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
|
||||||
|
:param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
:param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`.
|
||||||
|
:returns: cache directory tied to the user
|
||||||
|
"""
|
||||||
|
return PlatformDirs(appname=appname, appauthor=appauthor, version=version, opinion=opinion).user_cache_dir
|
||||||
|
|
||||||
|
|
||||||
|
def user_state_dir(
|
||||||
|
appname: str | None = None,
|
||||||
|
appauthor: str | None | Literal[False] = None,
|
||||||
|
version: str | None = None,
|
||||||
|
roaming: bool = False,
|
||||||
|
) -> str:
|
||||||
|
"""
|
||||||
|
:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
|
||||||
|
:param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
|
||||||
|
:param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
:param roaming: See `roaming <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
:returns: state directory tied to the user
|
||||||
|
"""
|
||||||
|
return PlatformDirs(appname=appname, appauthor=appauthor, version=version, roaming=roaming).user_state_dir
|
||||||
|
|
||||||
|
|
||||||
|
def user_log_dir(
|
||||||
|
appname: str | None = None,
|
||||||
|
appauthor: str | None | Literal[False] = None,
|
||||||
|
version: str | None = None,
|
||||||
|
opinion: bool = True,
|
||||||
|
) -> str:
|
||||||
|
"""
|
||||||
|
:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
|
||||||
|
:param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
|
||||||
|
:param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
:param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`.
|
||||||
|
:returns: log directory tied to the user
|
||||||
|
"""
|
||||||
|
return PlatformDirs(appname=appname, appauthor=appauthor, version=version, opinion=opinion).user_log_dir
|
||||||
|
|
||||||
|
|
||||||
|
def user_documents_dir() -> str:
|
||||||
|
"""
|
||||||
|
:returns: documents directory tied to the user
|
||||||
|
"""
|
||||||
|
return PlatformDirs().user_documents_dir
|
||||||
|
|
||||||
|
|
||||||
|
def user_runtime_dir(
|
||||||
|
appname: str | None = None,
|
||||||
|
appauthor: str | None | Literal[False] = None,
|
||||||
|
version: str | None = None,
|
||||||
|
opinion: bool = True,
|
||||||
|
) -> str:
|
||||||
|
"""
|
||||||
|
:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
|
||||||
|
:param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
|
||||||
|
:param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
:param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.
|
||||||
|
:returns: runtime directory tied to the user
|
||||||
|
"""
|
||||||
|
return PlatformDirs(appname=appname, appauthor=appauthor, version=version, opinion=opinion).user_runtime_dir
|
||||||
|
|
||||||
|
|
||||||
|
def user_data_path(
|
||||||
|
appname: str | None = None,
|
||||||
|
appauthor: str | None | Literal[False] = None,
|
||||||
|
version: str | None = None,
|
||||||
|
roaming: bool = False,
|
||||||
|
) -> Path:
|
||||||
|
"""
|
||||||
|
:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
|
||||||
|
:param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
|
||||||
|
:param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
:param roaming: See `roaming <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
:returns: data path tied to the user
|
||||||
|
"""
|
||||||
|
return PlatformDirs(appname=appname, appauthor=appauthor, version=version, roaming=roaming).user_data_path
|
||||||
|
|
||||||
|
|
||||||
|
def site_data_path(
|
||||||
|
appname: str | None = None,
|
||||||
|
appauthor: str | None | Literal[False] = None,
|
||||||
|
version: str | None = None,
|
||||||
|
multipath: bool = False,
|
||||||
|
) -> Path:
|
||||||
|
"""
|
||||||
|
:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
|
||||||
|
:param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
|
||||||
|
:param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
:param multipath: See `multipath <platformdirs.api.PlatformDirsABC.multipath>`.
|
||||||
|
:returns: data path shared by users
|
||||||
|
"""
|
||||||
|
return PlatformDirs(appname=appname, appauthor=appauthor, version=version, multipath=multipath).site_data_path
|
||||||
|
|
||||||
|
|
||||||
|
def user_config_path(
|
||||||
|
appname: str | None = None,
|
||||||
|
appauthor: str | None | Literal[False] = None,
|
||||||
|
version: str | None = None,
|
||||||
|
roaming: bool = False,
|
||||||
|
) -> Path:
|
||||||
|
"""
|
||||||
|
:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
|
||||||
|
:param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
|
||||||
|
:param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
:param roaming: See `roaming <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
:returns: config path tied to the user
|
||||||
|
"""
|
||||||
|
return PlatformDirs(appname=appname, appauthor=appauthor, version=version, roaming=roaming).user_config_path
|
||||||
|
|
||||||
|
|
||||||
|
def site_config_path(
|
||||||
|
appname: str | None = None,
|
||||||
|
appauthor: str | None | Literal[False] = None,
|
||||||
|
version: str | None = None,
|
||||||
|
multipath: bool = False,
|
||||||
|
) -> Path:
|
||||||
|
"""
|
||||||
|
:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
|
||||||
|
:param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
|
||||||
|
:param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
:param multipath: See `roaming <platformdirs.api.PlatformDirsABC.multipath>`.
|
||||||
|
:returns: config path shared by the users
|
||||||
|
"""
|
||||||
|
return PlatformDirs(appname=appname, appauthor=appauthor, version=version, multipath=multipath).site_config_path
|
||||||
|
|
||||||
|
|
||||||
|
def user_cache_path(
|
||||||
|
appname: str | None = None,
|
||||||
|
appauthor: str | None | Literal[False] = None,
|
||||||
|
version: str | None = None,
|
||||||
|
opinion: bool = True,
|
||||||
|
) -> Path:
|
||||||
|
"""
|
||||||
|
:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
|
||||||
|
:param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
|
||||||
|
:param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
:param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`.
|
||||||
|
:returns: cache path tied to the user
|
||||||
|
"""
|
||||||
|
return PlatformDirs(appname=appname, appauthor=appauthor, version=version, opinion=opinion).user_cache_path
|
||||||
|
|
||||||
|
|
||||||
|
def user_state_path(
|
||||||
|
appname: str | None = None,
|
||||||
|
appauthor: str | None | Literal[False] = None,
|
||||||
|
version: str | None = None,
|
||||||
|
roaming: bool = False,
|
||||||
|
) -> Path:
|
||||||
|
"""
|
||||||
|
:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
|
||||||
|
:param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
|
||||||
|
:param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
:param roaming: See `roaming <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
:returns: state path tied to the user
|
||||||
|
"""
|
||||||
|
return PlatformDirs(appname=appname, appauthor=appauthor, version=version, roaming=roaming).user_state_path
|
||||||
|
|
||||||
|
|
||||||
|
def user_log_path(
|
||||||
|
appname: str | None = None,
|
||||||
|
appauthor: str | None | Literal[False] = None,
|
||||||
|
version: str | None = None,
|
||||||
|
opinion: bool = True,
|
||||||
|
) -> Path:
|
||||||
|
"""
|
||||||
|
:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
|
||||||
|
:param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
|
||||||
|
:param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
:param opinion: See `roaming <platformdirs.api.PlatformDirsABC.opinion>`.
|
||||||
|
:returns: log path tied to the user
|
||||||
|
"""
|
||||||
|
return PlatformDirs(appname=appname, appauthor=appauthor, version=version, opinion=opinion).user_log_path
|
||||||
|
|
||||||
|
|
||||||
|
def user_documents_path() -> Path:
|
||||||
|
"""
|
||||||
|
:returns: documents path tied to the user
|
||||||
|
"""
|
||||||
|
return PlatformDirs().user_documents_path
|
||||||
|
|
||||||
|
|
||||||
|
def user_runtime_path(
|
||||||
|
appname: str | None = None,
|
||||||
|
appauthor: str | None | Literal[False] = None,
|
||||||
|
version: str | None = None,
|
||||||
|
opinion: bool = True,
|
||||||
|
) -> Path:
|
||||||
|
"""
|
||||||
|
:param appname: See `appname <platformdirs.api.PlatformDirsABC.appname>`.
|
||||||
|
:param appauthor: See `appauthor <platformdirs.api.PlatformDirsABC.appauthor>`.
|
||||||
|
:param version: See `version <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
:param opinion: See `opinion <platformdirs.api.PlatformDirsABC.opinion>`.
|
||||||
|
:returns: runtime path tied to the user
|
||||||
|
"""
|
||||||
|
return PlatformDirs(appname=appname, appauthor=appauthor, version=version, opinion=opinion).user_runtime_path
|
||||||
|
|
||||||
|
|
||||||
|
__all__ = [
|
||||||
|
"__version__",
|
||||||
|
"__version_info__",
|
||||||
|
"PlatformDirs",
|
||||||
|
"AppDirs",
|
||||||
|
"PlatformDirsABC",
|
||||||
|
"user_data_dir",
|
||||||
|
"user_config_dir",
|
||||||
|
"user_cache_dir",
|
||||||
|
"user_state_dir",
|
||||||
|
"user_log_dir",
|
||||||
|
"user_documents_dir",
|
||||||
|
"user_runtime_dir",
|
||||||
|
"site_data_dir",
|
||||||
|
"site_config_dir",
|
||||||
|
"user_data_path",
|
||||||
|
"user_config_path",
|
||||||
|
"user_cache_path",
|
||||||
|
"user_state_path",
|
||||||
|
"user_log_path",
|
||||||
|
"user_documents_path",
|
||||||
|
"user_runtime_path",
|
||||||
|
"site_data_path",
|
||||||
|
"site_config_path",
|
||||||
|
]
|
||||||
|
|
@ -0,0 +1,46 @@
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from platformdirs import PlatformDirs, __version__
|
||||||
|
|
||||||
|
PROPS = (
|
||||||
|
"user_data_dir",
|
||||||
|
"user_config_dir",
|
||||||
|
"user_cache_dir",
|
||||||
|
"user_state_dir",
|
||||||
|
"user_log_dir",
|
||||||
|
"user_documents_dir",
|
||||||
|
"user_runtime_dir",
|
||||||
|
"site_data_dir",
|
||||||
|
"site_config_dir",
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def main() -> None:
|
||||||
|
app_name = "MyApp"
|
||||||
|
app_author = "MyCompany"
|
||||||
|
|
||||||
|
print(f"-- platformdirs {__version__} --")
|
||||||
|
|
||||||
|
print("-- app dirs (with optional 'version')")
|
||||||
|
dirs = PlatformDirs(app_name, app_author, version="1.0")
|
||||||
|
for prop in PROPS:
|
||||||
|
print(f"{prop}: {getattr(dirs, prop)}")
|
||||||
|
|
||||||
|
print("\n-- app dirs (without optional 'version')")
|
||||||
|
dirs = PlatformDirs(app_name, app_author)
|
||||||
|
for prop in PROPS:
|
||||||
|
print(f"{prop}: {getattr(dirs, prop)}")
|
||||||
|
|
||||||
|
print("\n-- app dirs (without optional 'appauthor')")
|
||||||
|
dirs = PlatformDirs(app_name)
|
||||||
|
for prop in PROPS:
|
||||||
|
print(f"{prop}: {getattr(dirs, prop)}")
|
||||||
|
|
||||||
|
print("\n-- app dirs (with disabled 'appauthor')")
|
||||||
|
dirs = PlatformDirs(app_name, appauthor=False)
|
||||||
|
for prop in PROPS:
|
||||||
|
print(f"{prop}: {getattr(dirs, prop)}")
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
main()
|
||||||
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
|
|
@ -0,0 +1,120 @@
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import os
|
||||||
|
import re
|
||||||
|
import sys
|
||||||
|
from functools import lru_cache
|
||||||
|
from typing import cast
|
||||||
|
|
||||||
|
from .api import PlatformDirsABC
|
||||||
|
|
||||||
|
|
||||||
|
class Android(PlatformDirsABC):
|
||||||
|
"""
|
||||||
|
Follows the guidance `from here <https://android.stackexchange.com/a/216132>`_. Makes use of the
|
||||||
|
`appname <platformdirs.api.PlatformDirsABC.appname>` and
|
||||||
|
`version <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
"""
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_data_dir(self) -> str:
|
||||||
|
""":return: data directory tied to the user, e.g. ``/data/user/<userid>/<packagename>/files/<AppName>``"""
|
||||||
|
return self._append_app_name_and_version(cast(str, _android_folder()), "files")
|
||||||
|
|
||||||
|
@property
|
||||||
|
def site_data_dir(self) -> str:
|
||||||
|
""":return: data directory shared by users, same as `user_data_dir`"""
|
||||||
|
return self.user_data_dir
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_config_dir(self) -> str:
|
||||||
|
"""
|
||||||
|
:return: config directory tied to the user, e.g. ``/data/user/<userid>/<packagename>/shared_prefs/<AppName>``
|
||||||
|
"""
|
||||||
|
return self._append_app_name_and_version(cast(str, _android_folder()), "shared_prefs")
|
||||||
|
|
||||||
|
@property
|
||||||
|
def site_config_dir(self) -> str:
|
||||||
|
""":return: config directory shared by the users, same as `user_config_dir`"""
|
||||||
|
return self.user_config_dir
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_cache_dir(self) -> str:
|
||||||
|
""":return: cache directory tied to the user, e.g. e.g. ``/data/user/<userid>/<packagename>/cache/<AppName>``"""
|
||||||
|
return self._append_app_name_and_version(cast(str, _android_folder()), "cache")
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_state_dir(self) -> str:
|
||||||
|
""":return: state directory tied to the user, same as `user_data_dir`"""
|
||||||
|
return self.user_data_dir
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_log_dir(self) -> str:
|
||||||
|
"""
|
||||||
|
:return: log directory tied to the user, same as `user_cache_dir` if not opinionated else ``log`` in it,
|
||||||
|
e.g. ``/data/user/<userid>/<packagename>/cache/<AppName>/log``
|
||||||
|
"""
|
||||||
|
path = self.user_cache_dir
|
||||||
|
if self.opinion:
|
||||||
|
path = os.path.join(path, "log")
|
||||||
|
return path
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_documents_dir(self) -> str:
|
||||||
|
"""
|
||||||
|
:return: documents directory tied to the user e.g. ``/storage/emulated/0/Documents``
|
||||||
|
"""
|
||||||
|
return _android_documents_folder()
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_runtime_dir(self) -> str:
|
||||||
|
"""
|
||||||
|
:return: runtime directory tied to the user, same as `user_cache_dir` if not opinionated else ``tmp`` in it,
|
||||||
|
e.g. ``/data/user/<userid>/<packagename>/cache/<AppName>/tmp``
|
||||||
|
"""
|
||||||
|
path = self.user_cache_dir
|
||||||
|
if self.opinion:
|
||||||
|
path = os.path.join(path, "tmp")
|
||||||
|
return path
|
||||||
|
|
||||||
|
|
||||||
|
@lru_cache(maxsize=1)
|
||||||
|
def _android_folder() -> str | None:
|
||||||
|
""":return: base folder for the Android OS or None if cannot be found"""
|
||||||
|
try:
|
||||||
|
# First try to get path to android app via pyjnius
|
||||||
|
from jnius import autoclass
|
||||||
|
|
||||||
|
Context = autoclass("android.content.Context") # noqa: N806
|
||||||
|
result: str | None = Context.getFilesDir().getParentFile().getAbsolutePath()
|
||||||
|
except Exception:
|
||||||
|
# if fails find an android folder looking path on the sys.path
|
||||||
|
pattern = re.compile(r"/data/(data|user/\d+)/(.+)/files")
|
||||||
|
for path in sys.path:
|
||||||
|
if pattern.match(path):
|
||||||
|
result = path.split("/files")[0]
|
||||||
|
break
|
||||||
|
else:
|
||||||
|
result = None
|
||||||
|
return result
|
||||||
|
|
||||||
|
|
||||||
|
@lru_cache(maxsize=1)
|
||||||
|
def _android_documents_folder() -> str:
|
||||||
|
""":return: documents folder for the Android OS"""
|
||||||
|
# Get directories with pyjnius
|
||||||
|
try:
|
||||||
|
from jnius import autoclass
|
||||||
|
|
||||||
|
Context = autoclass("android.content.Context") # noqa: N806
|
||||||
|
Environment = autoclass("android.os.Environment") # noqa: N806
|
||||||
|
documents_dir: str = Context.getExternalFilesDir(Environment.DIRECTORY_DOCUMENTS).getAbsolutePath()
|
||||||
|
except Exception:
|
||||||
|
documents_dir = "/storage/emulated/0/Documents"
|
||||||
|
|
||||||
|
return documents_dir
|
||||||
|
|
||||||
|
|
||||||
|
__all__ = [
|
||||||
|
"Android",
|
||||||
|
]
|
||||||
|
|
@ -0,0 +1,156 @@
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import os
|
||||||
|
import sys
|
||||||
|
from abc import ABC, abstractmethod
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
if sys.version_info >= (3, 8): # pragma: no branch
|
||||||
|
from typing import Literal # pragma: no cover
|
||||||
|
|
||||||
|
|
||||||
|
class PlatformDirsABC(ABC):
|
||||||
|
"""
|
||||||
|
Abstract base class for platform directories.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(
|
||||||
|
self,
|
||||||
|
appname: str | None = None,
|
||||||
|
appauthor: str | None | Literal[False] = None,
|
||||||
|
version: str | None = None,
|
||||||
|
roaming: bool = False,
|
||||||
|
multipath: bool = False,
|
||||||
|
opinion: bool = True,
|
||||||
|
):
|
||||||
|
"""
|
||||||
|
Create a new platform directory.
|
||||||
|
|
||||||
|
:param appname: See `appname`.
|
||||||
|
:param appauthor: See `appauthor`.
|
||||||
|
:param version: See `version`.
|
||||||
|
:param roaming: See `roaming`.
|
||||||
|
:param multipath: See `multipath`.
|
||||||
|
:param opinion: See `opinion`.
|
||||||
|
"""
|
||||||
|
self.appname = appname #: The name of application.
|
||||||
|
self.appauthor = appauthor
|
||||||
|
"""
|
||||||
|
The name of the app author or distributing body for this application. Typically, it is the owning company name.
|
||||||
|
Defaults to `appname`. You may pass ``False`` to disable it.
|
||||||
|
"""
|
||||||
|
self.version = version
|
||||||
|
"""
|
||||||
|
An optional version path element to append to the path. You might want to use this if you want multiple versions
|
||||||
|
of your app to be able to run independently. If used, this would typically be ``<major>.<minor>``.
|
||||||
|
"""
|
||||||
|
self.roaming = roaming
|
||||||
|
"""
|
||||||
|
Whether to use the roaming appdata directory on Windows. That means that for users on a Windows network setup
|
||||||
|
for roaming profiles, this user data will be synced on login (see
|
||||||
|
`here <http://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx>`_).
|
||||||
|
"""
|
||||||
|
self.multipath = multipath
|
||||||
|
"""
|
||||||
|
An optional parameter only applicable to Unix/Linux which indicates that the entire list of data dirs should be
|
||||||
|
returned. By default, the first item would only be returned.
|
||||||
|
"""
|
||||||
|
self.opinion = opinion #: A flag to indicating to use opinionated values.
|
||||||
|
|
||||||
|
def _append_app_name_and_version(self, *base: str) -> str:
|
||||||
|
params = list(base[1:])
|
||||||
|
if self.appname:
|
||||||
|
params.append(self.appname)
|
||||||
|
if self.version:
|
||||||
|
params.append(self.version)
|
||||||
|
return os.path.join(base[0], *params)
|
||||||
|
|
||||||
|
@property
|
||||||
|
@abstractmethod
|
||||||
|
def user_data_dir(self) -> str:
|
||||||
|
""":return: data directory tied to the user"""
|
||||||
|
|
||||||
|
@property
|
||||||
|
@abstractmethod
|
||||||
|
def site_data_dir(self) -> str:
|
||||||
|
""":return: data directory shared by users"""
|
||||||
|
|
||||||
|
@property
|
||||||
|
@abstractmethod
|
||||||
|
def user_config_dir(self) -> str:
|
||||||
|
""":return: config directory tied to the user"""
|
||||||
|
|
||||||
|
@property
|
||||||
|
@abstractmethod
|
||||||
|
def site_config_dir(self) -> str:
|
||||||
|
""":return: config directory shared by the users"""
|
||||||
|
|
||||||
|
@property
|
||||||
|
@abstractmethod
|
||||||
|
def user_cache_dir(self) -> str:
|
||||||
|
""":return: cache directory tied to the user"""
|
||||||
|
|
||||||
|
@property
|
||||||
|
@abstractmethod
|
||||||
|
def user_state_dir(self) -> str:
|
||||||
|
""":return: state directory tied to the user"""
|
||||||
|
|
||||||
|
@property
|
||||||
|
@abstractmethod
|
||||||
|
def user_log_dir(self) -> str:
|
||||||
|
""":return: log directory tied to the user"""
|
||||||
|
|
||||||
|
@property
|
||||||
|
@abstractmethod
|
||||||
|
def user_documents_dir(self) -> str:
|
||||||
|
""":return: documents directory tied to the user"""
|
||||||
|
|
||||||
|
@property
|
||||||
|
@abstractmethod
|
||||||
|
def user_runtime_dir(self) -> str:
|
||||||
|
""":return: runtime directory tied to the user"""
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_data_path(self) -> Path:
|
||||||
|
""":return: data path tied to the user"""
|
||||||
|
return Path(self.user_data_dir)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def site_data_path(self) -> Path:
|
||||||
|
""":return: data path shared by users"""
|
||||||
|
return Path(self.site_data_dir)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_config_path(self) -> Path:
|
||||||
|
""":return: config path tied to the user"""
|
||||||
|
return Path(self.user_config_dir)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def site_config_path(self) -> Path:
|
||||||
|
""":return: config path shared by the users"""
|
||||||
|
return Path(self.site_config_dir)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_cache_path(self) -> Path:
|
||||||
|
""":return: cache path tied to the user"""
|
||||||
|
return Path(self.user_cache_dir)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_state_path(self) -> Path:
|
||||||
|
""":return: state path tied to the user"""
|
||||||
|
return Path(self.user_state_dir)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_log_path(self) -> Path:
|
||||||
|
""":return: log path tied to the user"""
|
||||||
|
return Path(self.user_log_dir)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_documents_path(self) -> Path:
|
||||||
|
""":return: documents path tied to the user"""
|
||||||
|
return Path(self.user_documents_dir)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_runtime_path(self) -> Path:
|
||||||
|
""":return: runtime path tied to the user"""
|
||||||
|
return Path(self.user_runtime_dir)
|
||||||
|
|
@ -0,0 +1,64 @@
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import os
|
||||||
|
|
||||||
|
from .api import PlatformDirsABC
|
||||||
|
|
||||||
|
|
||||||
|
class MacOS(PlatformDirsABC):
|
||||||
|
"""
|
||||||
|
Platform directories for the macOS operating system. Follows the guidance from `Apple documentation
|
||||||
|
<https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/MacOSXDirectories/MacOSXDirectories.html>`_.
|
||||||
|
Makes use of the `appname <platformdirs.api.PlatformDirsABC.appname>` and
|
||||||
|
`version <platformdirs.api.PlatformDirsABC.version>`.
|
||||||
|
"""
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_data_dir(self) -> str:
|
||||||
|
""":return: data directory tied to the user, e.g. ``~/Library/Application Support/$appname/$version``"""
|
||||||
|
return self._append_app_name_and_version(os.path.expanduser("~/Library/Application Support/"))
|
||||||
|
|
||||||
|
@property
|
||||||
|
def site_data_dir(self) -> str:
|
||||||
|
""":return: data directory shared by users, e.g. ``/Library/Application Support/$appname/$version``"""
|
||||||
|
return self._append_app_name_and_version("/Library/Application Support")
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_config_dir(self) -> str:
|
||||||
|
""":return: config directory tied to the user, e.g. ``~/Library/Preferences/$appname/$version``"""
|
||||||
|
return self._append_app_name_and_version(os.path.expanduser("~/Library/Preferences/"))
|
||||||
|
|
||||||
|
@property
|
||||||
|
def site_config_dir(self) -> str:
|
||||||
|
""":return: config directory shared by the users, e.g. ``/Library/Preferences/$appname``"""
|
||||||
|
return self._append_app_name_and_version("/Library/Preferences")
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_cache_dir(self) -> str:
|
||||||
|
""":return: cache directory tied to the user, e.g. ``~/Library/Caches/$appname/$version``"""
|
||||||
|
return self._append_app_name_and_version(os.path.expanduser("~/Library/Caches"))
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_state_dir(self) -> str:
|
||||||
|
""":return: state directory tied to the user, same as `user_data_dir`"""
|
||||||
|
return self.user_data_dir
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_log_dir(self) -> str:
|
||||||
|
""":return: log directory tied to the user, e.g. ``~/Library/Logs/$appname/$version``"""
|
||||||
|
return self._append_app_name_and_version(os.path.expanduser("~/Library/Logs"))
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_documents_dir(self) -> str:
|
||||||
|
""":return: documents directory tied to the user, e.g. ``~/Documents``"""
|
||||||
|
return os.path.expanduser("~/Documents")
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_runtime_dir(self) -> str:
|
||||||
|
""":return: runtime directory tied to the user, e.g. ``~/Library/Caches/TemporaryItems/$appname/$version``"""
|
||||||
|
return self._append_app_name_and_version(os.path.expanduser("~/Library/Caches/TemporaryItems"))
|
||||||
|
|
||||||
|
|
||||||
|
__all__ = [
|
||||||
|
"MacOS",
|
||||||
|
]
|
||||||
|
|
@ -0,0 +1,181 @@
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import os
|
||||||
|
import sys
|
||||||
|
from configparser import ConfigParser
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
from .api import PlatformDirsABC
|
||||||
|
|
||||||
|
if sys.platform.startswith("linux"): # pragma: no branch # no op check, only to please the type checker
|
||||||
|
from os import getuid
|
||||||
|
else:
|
||||||
|
|
||||||
|
def getuid() -> int:
|
||||||
|
raise RuntimeError("should only be used on Linux")
|
||||||
|
|
||||||
|
|
||||||
|
class Unix(PlatformDirsABC):
|
||||||
|
"""
|
||||||
|
On Unix/Linux, we follow the
|
||||||
|
`XDG Basedir Spec <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_. The spec allows
|
||||||
|
overriding directories with environment variables. The examples show are the default values, alongside the name of
|
||||||
|
the environment variable that overrides them. Makes use of the
|
||||||
|
`appname <platformdirs.api.PlatformDirsABC.appname>`,
|
||||||
|
`version <platformdirs.api.PlatformDirsABC.version>`,
|
||||||
|
`multipath <platformdirs.api.PlatformDirsABC.multipath>`,
|
||||||
|
`opinion <platformdirs.api.PlatformDirsABC.opinion>`.
|
||||||
|
"""
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_data_dir(self) -> str:
|
||||||
|
"""
|
||||||
|
:return: data directory tied to the user, e.g. ``~/.local/share/$appname/$version`` or
|
||||||
|
``$XDG_DATA_HOME/$appname/$version``
|
||||||
|
"""
|
||||||
|
path = os.environ.get("XDG_DATA_HOME", "")
|
||||||
|
if not path.strip():
|
||||||
|
path = os.path.expanduser("~/.local/share")
|
||||||
|
return self._append_app_name_and_version(path)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def site_data_dir(self) -> str:
|
||||||
|
"""
|
||||||
|
:return: data directories shared by users (if `multipath <platformdirs.api.PlatformDirsABC.multipath>` is
|
||||||
|
enabled and ``XDG_DATA_DIR`` is set and a multi path the response is also a multi path separated by the OS
|
||||||
|
path separator), e.g. ``/usr/local/share/$appname/$version`` or ``/usr/share/$appname/$version``
|
||||||
|
"""
|
||||||
|
# XDG default for $XDG_DATA_DIRS; only first, if multipath is False
|
||||||
|
path = os.environ.get("XDG_DATA_DIRS", "")
|
||||||
|
if not path.strip():
|
||||||
|
path = f"/usr/local/share{os.pathsep}/usr/share"
|
||||||
|
return self._with_multi_path(path)
|
||||||
|
|
||||||
|
def _with_multi_path(self, path: str) -> str:
|
||||||
|
path_list = path.split(os.pathsep)
|
||||||
|
if not self.multipath:
|
||||||
|
path_list = path_list[0:1]
|
||||||
|
path_list = [self._append_app_name_and_version(os.path.expanduser(p)) for p in path_list]
|
||||||
|
return os.pathsep.join(path_list)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_config_dir(self) -> str:
|
||||||
|
"""
|
||||||
|
:return: config directory tied to the user, e.g. ``~/.config/$appname/$version`` or
|
||||||
|
``$XDG_CONFIG_HOME/$appname/$version``
|
||||||
|
"""
|
||||||
|
path = os.environ.get("XDG_CONFIG_HOME", "")
|
||||||
|
if not path.strip():
|
||||||
|
path = os.path.expanduser("~/.config")
|
||||||
|
return self._append_app_name_and_version(path)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def site_config_dir(self) -> str:
|
||||||
|
"""
|
||||||
|
:return: config directories shared by users (if `multipath <platformdirs.api.PlatformDirsABC.multipath>`
|
||||||
|
is enabled and ``XDG_DATA_DIR`` is set and a multi path the response is also a multi path separated by the OS
|
||||||
|
path separator), e.g. ``/etc/xdg/$appname/$version``
|
||||||
|
"""
|
||||||
|
# XDG default for $XDG_CONFIG_DIRS only first, if multipath is False
|
||||||
|
path = os.environ.get("XDG_CONFIG_DIRS", "")
|
||||||
|
if not path.strip():
|
||||||
|
path = "/etc/xdg"
|
||||||
|
return self._with_multi_path(path)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_cache_dir(self) -> str:
|
||||||
|
"""
|
||||||
|
:return: cache directory tied to the user, e.g. ``~/.cache/$appname/$version`` or
|
||||||
|
``~/$XDG_CACHE_HOME/$appname/$version``
|
||||||
|
"""
|
||||||
|
path = os.environ.get("XDG_CACHE_HOME", "")
|
||||||
|
if not path.strip():
|
||||||
|
path = os.path.expanduser("~/.cache")
|
||||||
|
return self._append_app_name_and_version(path)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_state_dir(self) -> str:
|
||||||
|
"""
|
||||||
|
:return: state directory tied to the user, e.g. ``~/.local/state/$appname/$version`` or
|
||||||
|
``$XDG_STATE_HOME/$appname/$version``
|
||||||
|
"""
|
||||||
|
path = os.environ.get("XDG_STATE_HOME", "")
|
||||||
|
if not path.strip():
|
||||||
|
path = os.path.expanduser("~/.local/state")
|
||||||
|
return self._append_app_name_and_version(path)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_log_dir(self) -> str:
|
||||||
|
"""
|
||||||
|
:return: log directory tied to the user, same as `user_state_dir` if not opinionated else ``log`` in it
|
||||||
|
"""
|
||||||
|
path = self.user_state_dir
|
||||||
|
if self.opinion:
|
||||||
|
path = os.path.join(path, "log")
|
||||||
|
return path
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_documents_dir(self) -> str:
|
||||||
|
"""
|
||||||
|
:return: documents directory tied to the user, e.g. ``~/Documents``
|
||||||
|
"""
|
||||||
|
documents_dir = _get_user_dirs_folder("XDG_DOCUMENTS_DIR")
|
||||||
|
if documents_dir is None:
|
||||||
|
documents_dir = os.environ.get("XDG_DOCUMENTS_DIR", "").strip()
|
||||||
|
if not documents_dir:
|
||||||
|
documents_dir = os.path.expanduser("~/Documents")
|
||||||
|
|
||||||
|
return documents_dir
|
||||||
|
|
||||||
|
@property
|
||||||
|
def user_runtime_dir(self) -> str:
|
||||||
|
"""
|
||||||
|
:return: runtime directory tied to the user, e.g. ``/run/user/$(id -u)/$appname/$version`` or
|
||||||
|
``$XDG_RUNTIME_DIR/$appname/$version``
|
||||||
|
"""
|
||||||
|
path = os.environ.get("XDG_RUNTIME_DIR", "")
|
||||||
|
if not path.strip():
|
||||||
|
path = f"/run/user/{getuid()}"
|
||||||
|
return self._append_app_name_and_version(path)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def site_data_path(self) -> Path:
|
||||||
|
""":return: data path shared by users. Only return first item, even if ``multipath`` is set to ``True``"""
|
||||||
|
return self._first_item_as_path_if_multipath(self.site_data_dir)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def site_config_path(self) -> Path:
|
||||||
|
""":return: config path shared by the users. Only return first item, even if ``multipath`` is set to ``True``"""
|
||||||
|
return self._first_item_as_path_if_multipath(self.site_config_dir)
|
||||||
|
|
||||||
|
def _first_item_as_path_if_multipath(self, directory: str) -> Path:
|
||||||
|
if self.multipath:
|
||||||
|
# If multipath is True, the first path is returned.
|
||||||
|
directory = directory.split(os.pathsep)[0]
|
||||||
|
return Path(directory)
|
||||||
|
|
||||||
|
|
||||||
|
def _get_user_dirs_folder(key: str) -> str | None:
|
||||||
|
"""Return directory from user-dirs.dirs config file. See https://freedesktop.org/wiki/Software/xdg-user-dirs/"""
|
||||||
|
user_dirs_config_path = os.path.join(Unix().user_config_dir, "user-dirs.dirs")
|
||||||
|
if os.path.exists(user_dirs_config_path):
|
||||||
|
parser = ConfigParser()
|
||||||
|
|
||||||
|
with open(user_dirs_config_path) as stream:
|
||||||
|
# Add fake section header, so ConfigParser doesn't complain
|
||||||
|
parser.read_string(f"[top]\n{stream.read()}")
|
||||||
|
|
||||||
|
if key not in parser["top"]:
|
||||||
|
return None
|
||||||
|
|
||||||
|
path = parser["top"][key].strip('"')
|
||||||
|
# Handle relative home paths
|
||||||
|
path = path.replace("$HOME", os.path.expanduser("~"))
|
||||||
|
return path
|
||||||
|
|
||||||
|
return None
|
||||||
|
|
||||||
|
|
||||||
|
__all__ = [
|
||||||
|
"Unix",
|
||||||
|
]
|
||||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue