diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index e302cb43..e16c8ab1 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -24,11 +24,11 @@ repos: - id: end-of-file-fixer - id: trailing-whitespace - repo: https://github.com/tox-dev/pyproject-fmt - rev: v2.11.1 + rev: v2.16.2 hooks: - id: pyproject-fmt - repo: https://github.com/abravalheri/validate-pyproject - rev: v0.24.1 + rev: v0.25 hooks: - id: validate-pyproject - repo: https://github.com/sphinx-contrib/sphinx-lint @@ -37,14 +37,14 @@ repos: - id: sphinx-lint types: [rst] - repo: https://github.com/pycqa/isort - rev: 7.0.0 + rev: 8.0.1 hooks: - id: isort additional_dependencies: ["toml"] entry: isort --profile=black name: isort (python) - repo: https://github.com/psf/black-pre-commit-mirror - rev: 25.12.0 + rev: 26.1.0 hooks: - id: black - repo: https://github.com/tonybaloney/perflint diff --git a/docs/data-processing/apis/grpc/accounts_pb2.py b/docs/data-processing/apis/grpc/accounts_pb2.py index de7deae0..ca7d8e6a 100644 --- a/docs/data-processing/apis/grpc/accounts_pb2.py +++ b/docs/data-processing/apis/grpc/accounts_pb2.py @@ -6,6 +6,7 @@ # Generated by the protocol buffer compiler. DO NOT EDIT! # source: accounts.proto """Generated protocol buffer code.""" + from google.protobuf import descriptor as _descriptor from google.protobuf import message as _message from google.protobuf import reflection as _reflection diff --git a/docs/data-processing/apis/grpc/accounts_pb2_grpc.py b/docs/data-processing/apis/grpc/accounts_pb2_grpc.py index c6c2f83d..b3787a52 100644 --- a/docs/data-processing/apis/grpc/accounts_pb2_grpc.py +++ b/docs/data-processing/apis/grpc/accounts_pb2_grpc.py @@ -4,6 +4,7 @@ # Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT! """Client and server classes corresponding to protobuf-defined services.""" + import accounts_pb2 as accounts__pb2 import grpc diff --git a/docs/data-processing/serialisation-formats/json/index.rst b/docs/data-processing/serialisation-formats/json/index.rst index 850d9e7f..849e538e 100644 --- a/docs/data-processing/serialisation-formats/json/index.rst +++ b/docs/data-processing/serialisation-formats/json/index.rst @@ -236,6 +236,25 @@ JSON tools .. image:: https://raster.shields.io/github/license/stefankoegl/python-json-patch :alt: Licence +`jsonata-python `_ + `JSONata `_ is a lightweight query + and transformation language for JSON data, inspired by XPath. + + .. image:: https://raster.shields.io/github/stars/rayokota/jsonata-python + :alt: Stars + :target: https://github.com/rayokota/jsonata-python + + .. image:: https://raster.shields.io/github/contributors/rayokota/jsonata-python + :alt: Contributors + :target: https://github.com/rayokota/jsonata-python/graphs/contributors + + .. image:: https://raster.shields.io/github/commit-activity/y/rayokota/jsonata-python + :alt: Commit activity + :target: https://github.com/rayokota/jsonata-python/graphs/commit-activity + + .. image:: https://raster.shields.io/github/license/rayokota/jsonata-python + :alt: Lizenz + .. _`standard`: https://www.json.org/json-en.html .. _`JSON_Checker`: http://www.json.org/JSON_checker/ .. _`JSON Schema Proposal`: https://json-schema.org diff --git a/docs/performance/index.rst b/docs/performance/index.rst index 3fc5a60c..6f7adf55 100644 --- a/docs/performance/index.rst +++ b/docs/performance/index.rst @@ -21,6 +21,10 @@ it is usually counterproductive to worry about the efficiency of the code. `_, in Computer Programming as an Art (1974) +.. seealso:: + * `Speed up your data science and scientific computing code + `_ + k-Means example --------------- @@ -62,9 +66,19 @@ Performance measurements ------------------------ Once you have worked with your code, it can be useful to examine its efficiency -more closely. `cProfile -`_, -:doc:`ipython-profiler` or :doc:`scalene` can be used for this. +more closely. :doc:`cProfile `, :doc:`ipython-profiler`, +:doc:`scalene`, :doc:`tprof` or :doc:`memray` can be used for this. So far, I +usually carry out the following steps: + +:doc:`cProfile `, :doc:`ipython-profiler`, :doc:`scalene` +or :doc:`tprof` can be used for this. So far, I usually carry out the following +steps: + +#. I profile the entire programme with :doc:`cProfile ` or `py-spy + `_ to find slow functions. +#. Then I optimise a slow function. +#. Finally, I create a new profile and filter out the result of my optimised + version so that I can compare the results. .. versionadded:: Python3.15 :pep:`799` will provide a special profiling module that organises the @@ -72,8 +86,8 @@ more closely. `cProfile contains: :mod:`profiling.tracing` - deterministic function call tracing, which has been moved from `cProfile - `_. + deterministic function call tracing, which has been moved from + :doc:`cProfile `. :mod:`profiling.sampling` the new statistical sampling profiler :doc:`tachyon`. @@ -91,8 +105,11 @@ more closely. `cProfile :titlesonly: :maxdepth: 0 + tracing ipython-profiler.ipynb scalene.ipynb + tprof + memray tachyon Search for existing implementations @@ -282,6 +299,11 @@ scientific Python and NumPy code into fast machine code, for example: However, Numba requires `LLVM `_ and some Python constructs are not supported. +.. seealso:: + * `Speeding up NumPy with parallelism + by Itamar + Turner-Trauring`_ + Task planner ------------ diff --git a/docs/performance/memray-flamegraph.png b/docs/performance/memray-flamegraph.png new file mode 100644 index 00000000..abe56453 Binary files /dev/null and b/docs/performance/memray-flamegraph.png differ diff --git a/docs/performance/memray.rst b/docs/performance/memray.rst new file mode 100644 index 00000000..7706f95f --- /dev/null +++ b/docs/performance/memray.rst @@ -0,0 +1,93 @@ +.. SPDX-FileCopyrightText: 2026 Veit Schiele +.. +.. SPDX-License-Identifier: BSD-3-Clause + +Memray +====== + +Memory usage is difficult to control in Python projects because the language +does not explicitly indicate where memory is allocated, module imports can +significantly increase consumption, and it is all too easy to create a data +structure that accidentally grows indefinitely. Data science projects are +particularly prone to high memory consumption, as they usually import many large +dependencies such as :doc:`/workspace/numpy/index`, even if these are only used +in a few places. + +`Memray `_ helps you understand your +programme’s memory usage by tracking where memory is allocated and freed during +programme execution. This data can then be displayed in various ways, including +`flame graphs `_, which summarise +`stack traces `_ in a diagram, with +the bar width representing the size of the memory allocation. + +With ``memray run``, any Python command can be profiled. For most projects, it +is recommended to first use check to profile the function that loads your +project. This checks the minimum effort required to start your application, for +example: + +.. code-block:: console + + $ uv run memray run src/items/__init__.py check + Writing profile results into src/items/memray-__init__.py.72633.bin + [memray] Successfully generated profile results. + + You can now generate reports from the stored allocation records. + Some example commands to generate reports: + + /Users/veit/items/.venv/bin/python3 -m memray flamegraph src/items/memray-__init__.py.72633.bin + +The command outputs the message ``Successfully generated profile results.`` and +creates a :samp:`{PROCESS-ID}.bin` file. We can then create the flame graph +with: + +.. code-block:: console + + $ uv run python -m memray flamegraph src/items/memray-__init__.py.72633.bin + Wrote src/items/memray-flamegraph-__init__.py.72633.html + +.. tip:: + In many consoles, you can combine the two commands with ``&&``: + + .. code-block:: console + + $ uv run memray run src/items/__init__.py check && uv run python -m memray flamegraph src/items/memray-__init__.py.72633.bin + +The result is the following HTML file: + +.. figure:: memray-flamegraph.png + :alt: memray flamegraph report + + memray flamegraph report + +The header area of the page contains several controls, including + +*Memory Graph* + Display of the memory space of a process in the working memory (`resident + set size `_) and the + dynamic memory (heap memory) over time + die Zeit +*Stats* + Memory statistics, in this case + + .. code-block:: text + + Command line: /Users/veit/items/.venv/bin/memray run src/items/api.py check + Start time: Sun Feb 08 2026 12:12:27 GMT+0100 (Central European Standard Time) + End time: Sun Feb 08 2026 12:12:27 GMT+0100 (Central European Standard Time) + Duration: 0:00:00.068000 + Total number of allocations: 11142 + Total number of frames seen: 0 + Peak memory usage: 4.6 MB + Python allocator: pymalloc + +Below that is the flame graph as an icicle chart showing memory allocations over +time, with the last call at the bottom. The graph shows the line of code +executed at a given point in time, with the width proportional to the amount of +memory allocated; if you move your mouse over it, you will see further details +such as file name, line number, allocated memory and number of allocations. + +.. tip:: + With :ref:`python-basics:pytest_memray`, there is also a plugin for + :doc:`python-basics:test/pytest/index` that allows you to check whether the + upper limits you have set for memory consumption and memory leaks are being + adhered to. diff --git a/docs/performance/tprof.rst b/docs/performance/tprof.rst new file mode 100644 index 00000000..2376d18c --- /dev/null +++ b/docs/performance/tprof.rst @@ -0,0 +1,67 @@ +.. SPDX-FileCopyrightText: 2026 Veit Schiele +.. +.. SPDX-License-Identifier: BSD-3-Clause + +``tprof`` +========= + +`tprof `_ measures from Python 3.12 onwards +the time spent executing a module in specific functions. Unlike other profilers, +it only tracks the specified functions with :mod:`sys.monitoring`, eliminating +the need for filtering. + +``tprof`` supports use as a command line programme and with a Python interface: + +:samp:`uv run tprof -t {MODULE}:{FUNCTION} (-m {MODULE} | {PATH/TO/SCRIPT})` + Suppose you have determined that creating :class:`pathlib.Path` objects in + the :mod:`main` module is slowing down your code. Here’s how you can measure + this with ``tprof``: + + .. code-block:: console + + $ uv run tprof -t pathlib:Path.open -m main + 🎯 tprof results: + function calls total mean ± σ min … max + pathlib:Path.open() 1 93μs 93μs 93μs … 93μs + + With the ``-x`` option, you can also compare two functions with each other: + + .. code-block:: console + + $ uv run tprof -x -t old -m main -t new -m main + 🎯 tprof results: + function calls total mean ± σ min … max delta + main:old() 1 41μs 41μs 41μs … 41μs - + main:new() 1 20μs 20μs 20μs … 20μs -50.67% + +``tprof(*targets, label: str | None = None, compare: bool = False)`` + uses this code as a :doc:`context manager ` + in your code to perform profiling in a specific block. The report is + generated each time the block is run through. + + ``*targets`` + are callable elements for profiling or references to elements that are + resolved with :func:`pkgutil.resolve_name`. + ``label`` + is an optional string that can be added to the report as a header. + ``compare`` + set to ``True`` activates comparison mode. + + Example: + + .. code-block:: Python + + from pathlib import Path + + from tprof import tprof + + with tprof(Path.open): + p = Path("docs", "save-data", "myfile.txt") + f = p.open() + + .. code-block:: console + + $ uv run python main.py + 🎯 tprof results: + function calls total mean ± σ min … max + pathlib:Path.open() 1 82μs 82μs 82μs … 82μs diff --git a/docs/performance/tracing.rst b/docs/performance/tracing.rst new file mode 100644 index 00000000..9503a933 --- /dev/null +++ b/docs/performance/tracing.rst @@ -0,0 +1,45 @@ +.. SPDX-FileCopyrightText: 2026 Veit Schiele +.. +.. SPDX-License-Identifier: BSD-3-Clause + +cProfile/profiling.tracing +========================== + +Usually, a profile is created in the command line with `cProfile +`_ or, from +Python 3.15 onwards, with :mod:`profiling.tracing`, which then displays its +profile statistics. However, this can quickly become very tedious, especially +when reading extensive profiles or sorting the data. A more flexible approach is +to save the profile data in a file instead, which can then be read with the +:mod:`pstats` module: + +#. :samp:`uv run python -m cProfile -o {PROFILE} ({SCRIPT} | {-m {MODULE})` + runs `cProfile + `_ to + profile your script or module and saves the results in a file specified by + the ``-o`` option. + +#. :samp:`uv run python -m (cProfile | profiling.tracing) -o profile ({SCRIPT} | + -m {MODULE}) <<< $'sort cumtime\nstats 100' | less` passes the following two + commands to the :mod:`pstats` module using the ``$`` syntax. + + ``sort cumtime`` + sorts the output by cumulative time, starting with the largest. + + To sort by other metrics, simply replace ``cumtime`` with a value from + :meth:`pstats.Stats.sort_stats`. + + ``stats 100`` + displays the first 100 lines of the profile. + + The output is passed to ``less`` so you can view the results. Press :kbd:`q` + to exit when you are finished. + +#. Before and after optimisation can be easily compared, for example with: + + .. code-block:: console + + $ uv run python -m cProfile -o before.profile main.py + $ git switch -c main_optimisation + ... + $ uv run python -m cProfile -o after.profile main.py diff --git a/docs/productive/git/advanced/internals.rst b/docs/productive/git/advanced/internals.rst index 06653fb9..6a487a1a 100644 --- a/docs/productive/git/advanced/internals.rst +++ b/docs/productive/git/advanced/internals.rst @@ -2,12 +2,81 @@ .. .. SPDX-License-Identifier: BSD-3-Clause -Git’s database internals ------------------------- +Git Internals +============= + +So far, we have looked at how you can use Git to manage the different states of +your code. Now we want to show you the :ref:`data ` and +:ref:`storage models ` that underlie Git. + +Data Model +---------- + +You will be able to use Git more effectively once you understand the data model. +Git manages four types of data: + +Objects +~~~~~~~ + +.. include:: ../glossary.rst + :start-after: start-object + :end-before: end-object + +Commit +:::::: + +.. include:: ../glossary.rst + :start-after: start-commit + :end-before: end-commit + +Tree +:::: + +.. include:: ../glossary.rst + :start-after: start-tree + :end-before: end-tree + +Blob +:::: + +.. include:: ../glossary.rst + :start-after: start-blob + :end-before: end-blob + +Tag +::: + +.. include:: ../glossary.rst + :start-after: start-tag + :end-before: end-tag + +References +~~~~~~~~~~ + +.. include:: ../glossary.rst + :start-after: start-refs + :end-before: end-refs + +Index +~~~~~ + +.. include:: ../glossary.rst + :start-after: start-index + :end-before: end-index + +Reflog +~~~~~~ + +.. include:: ../glossary.rst + :start-after: start-reflog + :end-before: end-reflog + +.. _git-storage-model: + +Storage model +------------- .. seealso:: - * `Commits are snapshots, not diffs - `_ * Git’s database internals * `Part I: packed object store @@ -20,3 +89,10 @@ Git’s database internals `_ * `Part V: scalability `_ + +Packfiles +~~~~~~~~~ + +.. include:: ../glossary.rst + :start-after: start-packfile + :end-before: end-packfile diff --git a/docs/productive/git/branch.rst b/docs/productive/git/branch.rst index 81082922..39220a05 100644 --- a/docs/productive/git/branch.rst +++ b/docs/productive/git/branch.rst @@ -302,6 +302,8 @@ Delete branches * `Git Branching - Branches in a Nutshell `_ +.. _remote-branches: + Remote branches --------------- diff --git a/docs/productive/git/glossary.rst b/docs/productive/git/glossary.rst index 17663e39..b4c84e6a 100644 --- a/docs/productive/git/glossary.rst +++ b/docs/productive/git/glossary.rst @@ -7,22 +7,78 @@ Git glossary .. glossary:: + Blob + + .. _start-blob + + A blob object contains the contents of a file + + With each :term:`commit`, Git stores the entire contents of each file + you have changed as a blob. For example, if you have a commit that + changes two files in a repository, that commit creates two new blobs, so + commits take up relatively little storage space even in very large + repositories. + + .. _end-blob + Branch - A branch is a development line. The last commit on a branch is called - the tip of the branch, which is referenced by a ``head`` and which moves - on as more development is done on the branch. A single Git repository - can have any number of branches, but its :term:`Working Tree` is - associated with only one of them – the current or checked-out branch – + A branch is a line of development. The last :term:`commit` on a branch + is called the tip of the branch, which is referenced by a :term:`HEAD` + and moves forward as further development is made on the branch. A single + Git repository can have any number of branches, but your working tree is + only connected to one of them – the *current* or *checked-out* branch – and :term:`HEAD` points to that branch. Cache Obsolete for :term:`Index`. Clone - Local version of a repository including all commits and branches. + Local version of a repository including all :term:`commits ` and + :term:`branches `. Commit - A snapshot of the entire Git repository, compressed in a `SHA + .. _start-commit + + A commit is a snapshot of the entire Git repository that can be uniquely + identified by a `SHA + `_ value and + contains at least the following information: + + * Directory structure of all files in this version of the repository and + the contents of each file, stored as the :term:`tree` ID of the + top-level directory of the commit. + * ID(s) of the parent commit(s). The first commit of a repository has no + parent commits, regular commits have one parent commit, merge commits + have two or more parent commits. + * Author and time when the commit was created. + * Committer and time when the commit was committed. + * Commit message + + Example: + + .. code-block:: console + + $ git cat-file -p main + tree 47cc0283b10bd5e4e8a0d61537d13bba3bfad916 + parent 63825a43e213ef8a7904a8994976ac86284d32bd + author veit 1770370977 +0100 + committer veit 1770370977 +0100 + + :memo: Add links to Python speed + + Like all other objects, commits cannot be changed after they have been + created. So if you want to change a commit with ``git commit --amend``, + a new commit with the same parent is actually created. And even if you + display a commit with ``git show``, the diff is only calculated at that + point in time. + + .. seealso:: + * `Commits are snapshots, not diffs + `_ + + .. _end-commit + + A snapshot of the entire Git repository, compressed in a `SHA `_. Fork @@ -51,11 +107,36 @@ Git glossary ``HEAD`` The ``HEAD`` pointer represents your current working directory and can - be moved to different branches, tags or commits using git switch. + be moved to different :term:`branches `, :term:`tags ` or + :term: commits ` using ``git switch``. Index - A collection of files with status information whose content is saved as - objects. The index is a saved version of your :term:`Working Tree`. + Staging area + .. _start-index + + List of files and their contents stored as :term:`blob`. With ``git + add``, you can add files to the index or update the contents of a file + in the index. + + Unlike a :term:`tree`, the index is a flat list of files. When you + commit, Git converts the list of files in the index into a directory + tree and uses that tree for the new commit. Each index entry has four + fields: + + #. One of the following four file types: + + * regular file + * executable file + * symbolic link + * gitlink (for submodules) + + #. Blob ID of the file or commit ID of the submodule + #. Staging number, usually ``0``. However, in the event of a merge + conflict, there may be multiple versions of the same file name in the + index. + #. File path + + .. _end-index ``origin`` The usual upstream repository. Most projects have at least one upstream @@ -69,13 +150,241 @@ Git glossary ratings, comments, tests :abbr:`etc. (et cetera)`. .. seealso:: - * :doc:`advanced/gitlab/merge-requests`. - * :ref:`Merge or pull requests `. + * :doc:`advanced/gitlab/merge-requests` + * :ref:`Merge or pull requests ` + + Object + + .. _start-object + + All :term:`commits `, :term:`trees `, :term:`blobs + `, and :term:`tags ` in a Git repository are stored as Git + objects, which never change after they are created and have a unique ID, + such as ``3a5c279ea2f5d18498b61c229571d2449305a0``. This means that you + can use an object’s ID to restore its contents at any time, as long as + the object has not been deleted. + + .. seealso:: + * `Git Internals - Git Objects + `_ + + .. _end-object + + Packfile + + .. _start-packfile + + The format in which Git stores objects on the hard drive is called the + *loose* object format. However, to save space, Git occasionally packs + several of these objects into a single binary file called Packfile in + order to save space and work more efficiently. You can also perform + packing manually with ``git push`` or ``git gc``. This will delete most + of your objects in :file:`.git/objects/` and create a new pair of files: + + .. code-block:: console + + $ find .git/objects -type f + .git/objects/pack/pack-e9282cda3898f806f7bd108a3675c9e4d236915c.pack + .git/objects/pack/pack-e9282cda3898f806f7bd108a3675c9e4d236915c.idx + + :file:`*.pack` + contains the contents of all objects that have been removed from + your file system. + :file:`.idx` + contains the offsets of this pack file, allowing you to quickly jump + to a specific object. + + Any remaining objects are :term:`blobs ` that are not referenced + by any commit, known as *dangling references* , such as files in the + working directory that were never added to a commit. + + When Git packs objects, it looks for files with similar names and sizes + and only stores the deltas from one version of the file to the next. + With ``git verify-pack``, you can view the pack file and see how Git + saved storage space: + + .. code-block:: console + + $ git verify-pack -v .git/objects/pack/pack-e9282cda3898f806f7bd108a3675c9e4d236915c.pack + ... + dd1827ebf73b22d9f5828eec005eda4d79520f57 blob 147 140 389838 + 0a66f9a9ab72e3a99994803de8337f523b1b93d0 blob 31 43 389978 1 dd1827ebf73b22d9f5828eec005eda4d79520f57 + ... + .git/objects/pack/pack-e9282cda3898f806f7bd108a3675c9e4d236915c.pack: ok + + * :term:`Blob` ``0a66f9a`` refers to the following blob ``dd1827e``. + * The third column indicates the size of the object in the packfile, so + you can see that ``dd1827e`` takes up 147 bytes, while ``0a66f9a`` + only takes up 31 bytes. + * The current file is therefore stored unchanged, while the original + version is stored as a delta. This allows faster access to the latest + version of a file. + * The general syntax of ``git verify-pack -v`` is: + + :samp:`{OBJECT-ID} {TYPE} {SIZE} {SIZE-IN-PACKFILE} {OFFSET-IN-PACKFILE} [{DEPTH} {BASE-ID}]` + + .. seealso:: + * `Git Internals - Packfiles + `_ + * `git verify-pack `_ + + .. _end-packfile + + Reference + + .. _start-refs + + References are a way to give commits a name that is easier to remember, + such as for :doc:`branches `, :doc:`tags `, + :ref:`remote-branches`, and so on. Git often uses ``ref`` as an + abbreviation for such references. The most important references are: + + :samp:`.git/refs/heads/{BRANCHNAME}` + A branch refers to the ID of the latest :term:`commit` on that + :term:`branch`. To retrieve the history of commits on a branch, Git + starts with the commit ID that the branch points to and then looks + at the parent commits. References can refer to + + * an object ID, usually a commit ID + * another *symbolic* reference + + :samp:`.git/refs/tags/{TAGNAME}` + A tag refers to a commit ID, a tag object ID, or another object ID. + + ``.git/HEAD`` + :term:`HEAD` is where Git stores your current branch. ``HEAD`` can + be either + + * a symbolic reference to your current branch, for example ``ref: + refs/heads/main``. + * a direct reference to a commit ID if there is no current branch, + that is, in a *detached HEAD state*. + + :samp:`.git/refs/remotes/{REMOTE}/{BRANCHNAME}` + A remote tracking branch refers to a commit ID. You can update it + with ``git fetch`` if necessary, and if ``git status`` outputs + ``Your branch is up to date with 'origin/main'``, it refers to it. + + ``refs/remotes/{REMOTE}/HEAD`` is a symbolic reference to the + default branch of the remote repository. + + .. seealso:: + * `Git Internals - Git References + `_ + + .. _end-refs: + + Reflog + + .. _start-reflog + + Every time a :term:`branch`, a :ref:`remote tracking branch + , or :term:`HEAD` is updated, Git updates a log called + *reflog* for that reference, for example in + :file:`.git/logs/refs/heads/main`: + + .. code-block:: console + + 0000000000000000000000000000000000000000 492e16edcf9cdb3371492be59735e517a17cc86c veit 1739549686 +0100 clone: from github.com:cusyio/Python4DataScience-de.git + 492e16edcf9cdb3371492be59735e517a17cc86c c40bfa2a238e824b619f760494ce5ce0769851c3 veit 1739549907 +0100 commit: Update git docs + c40bfa2a238e824b619f760494ce5ce0769851c3 fa39661bb7fa93b420870845cb174529e8d62552 veit 1739549971 +0100 rebase (finish): refs/heads/main onto b7214df753ecbd01acd90d8f3dcd359e02441249 + ... + + Each entry in the reflog contains: + + * Commit ID + * Commit ID of the subsequent commits + * Author + * Email address + * Timestamp when the change was made + * Log message, for example: + + * :samp:`clone: from {REMOTE-URL}` + * :samp:`commit: {COMMIT-MESSAGE}` + * :samp:`rebase (finish): refs/heads/main onto {BASIC-COMMIT-ID}` + + Reflogs log changes made in your local repository. However, they are not + shared in the :term:`remote repository`. + + .. seealso:: + * :ref:`reflog` + + .. _end-reflog Remote repository shared repository, for example on :term:`GitLab`, for exchanging changes in a team. + Tag object + + .. _start-tag + + Tag objects contain at least the following fields: + + * of the object to which it refers + * Type of the object to which it refers + * Tag message + * Tagger and tag date + + Example: + + .. code-block:: console + + $ git cat-file -p 24.3.0 + object aa366cc9af3497544338482f82bdeb21f1dd3c21 + type commit + tag 24.3.0 + tagger Veit Schiele 1732086922 +0100 + + .. _end-tag + + Tree + + .. _start-tree + + Representation of a directory in Git and can contain files or other + trees (subdirectories). For each element in the tree, it lists the + following: + + * File name + * File type: + + * normal file + * executable file + * symbolic link + * directory + * gitlink (for submodules) + + * Object ID with the contents of the file, directory or gitlink + + Example: + + .. code-block:: console + + $ git cat-file -p main^{tree} + 040000 tree 2f59a223f7dc767f4776e77762d208fa72bfd343 .dvc + 040000 tree 75833fd33271db55b6f1c96915f60f98a60b51a0 .github + 100644 blob 36d2dc5a5228cbf65b8cfe913565c9be49db1a3d .gitignore + ... + $ git cat-file -p 2f59a223f7dc767f4776e77762d208fa72bfd343 + 100644 blob 669784da1fe0818e9abb795f73b7faf393832f2e .gitignore + 100644 blob 0a66f9a9ab72e3a99994803de8337f523b1b93d0 config + $ git cat-file -p 36d2dc5a5228cbf65b8cfe913565c9be49db1a3d + # SPDX-FileCopyrightText: 2019 Veit Schiele + # + # SPDX-License-Identifier: BSD-3-Clause + ... + + .. hint:: + The first column of a tree entry is roughly based on `Unix file + permissions + `_, + , but Git cannot actually manage Unix file permissions. Extensions + such as :doc:`/productive/git/advanced/etckeeper` are required for + this. + + .. _end-tree + Trunk-Based Development TBD Git workflow with short-lived topic branches that are quickly merged diff --git a/docs/productive/licensing.rst b/docs/productive/licensing.rst index 84f0a298..77d0a9d8 100644 --- a/docs/productive/licensing.rst +++ b/docs/productive/licensing.rst @@ -257,6 +257,9 @@ they lack required components and/or legal agreements: * Alek Tarkowski, Open Future in partnership with the Open Source Initiative: `Data Governance in Open Source AI `_ + * `Rethinking open source generative AI: open-washing and the EU AI Act + `_ + by Andreas Liesenfeld and Mark Dingemanse Databases ~~~~~~~~~ diff --git a/docs/productive/qa/requests/certs.py b/docs/productive/qa/requests/certs.py index 17f5b31e..33933e3c 100644 --- a/docs/productive/qa/requests/certs.py +++ b/docs/productive/qa/requests/certs.py @@ -12,6 +12,7 @@ environment, you can change the definition of where() to return a separately packaged CA bundle. """ + from certifi import where if __name__ == "__main__": diff --git a/docs/productive/qa/requests/exceptions.py b/docs/productive/qa/requests/exceptions.py index 9cce41c9..eef0fd55 100644 --- a/docs/productive/qa/requests/exceptions.py +++ b/docs/productive/qa/requests/exceptions.py @@ -6,6 +6,7 @@ This module contains the set of Requests' exceptions. """ + from urllib3.exceptions import HTTPError as BaseHTTPError diff --git a/docs/productive/qa/requests/hooks.py b/docs/productive/qa/requests/hooks.py index fb6450ee..663184b2 100644 --- a/docs/productive/qa/requests/hooks.py +++ b/docs/productive/qa/requests/hooks.py @@ -11,6 +11,7 @@ ``response``: The response generated from a Request. """ + HOOKS = ["response"] diff --git a/docs/productive/qa/requests/models.py b/docs/productive/qa/requests/models.py index 94c6a8e1..f8bf7b04 100644 --- a/docs/productive/qa/requests/models.py +++ b/docs/productive/qa/requests/models.py @@ -576,7 +576,7 @@ def prepare_body(self, data, files, json=None): else: # Multi-part file uploads. if files: - (body, content_type) = self._encode_files(files, data) + body, content_type = self._encode_files(files, data) else: if data: body = self._encode_params(data) diff --git a/docs/productive/qa/requests/sessions.py b/docs/productive/qa/requests/sessions.py index f73068a6..f0598abf 100644 --- a/docs/productive/qa/requests/sessions.py +++ b/docs/productive/qa/requests/sessions.py @@ -7,6 +7,7 @@ This module provides a Session object to manage and persist settings across requests (cookies, auth, proxies). """ + import os import sys import time diff --git a/docs/productive/security.rst b/docs/productive/security.rst index dfe0c412..fc99401b 100644 --- a/docs/productive/security.rst +++ b/docs/productive/security.rst @@ -92,8 +92,8 @@ Is there a safety concept for the project? Risk: Medium -Ideally, a :file:`SECURITY.md` or similar file should have been published with -the project. This file should contain information +Ideally, a :ref:`python-basics:security` or similar file should have been +published with the project. This file should contain information * how a security vulnerability can be reported without it becoming publicly visible,