Merge branch 'main' into 1656-CLI-repo-management

docs/source/de/_toctree.yml

@@ -33,4 +33,8 @@
     - local: guides/integrations
       title: Integrieren einer Bibliothek
     - local: guides/webhooks_server
-      title: Webhooks server
+      title: Webhooks server
+- title: "Konzeptionelle Anleitungen"
+  sections:
+    - local: concepts/git_vs_http
+      title: Git vs. HTTP-Paradigma

docs/source/de/concepts/git_vs_http.md

@@ -0,0 +1,69 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
+# Git vs. HTTP-Paradigma
+
+Die `huggingface_hub`-Bibliothek ist eine Bibliothek zur Interaktion mit dem Hugging Face 
+Hub, einer Sammlung von auf Git basierenden Repositories (Modelle, Datensätze oder 
+Spaces). Es gibt zwei Hauptmethoden, um auf den Hub mit `huggingface_hub` zuzugreifen.
+
+Der erste Ansatz, der sogenannte "Git-basierte" Ansatz, wird von der [`Repository`] Klasse 
+geleitet. Diese Methode verwendet einen Wrapper um den `git`-Befehl mit zusätzlichen 
+Funktionen, die speziell für die Interaktion mit dem Hub entwickelt wurden. Die zweite 
+Option, die als "HTTP-basierter" Ansatz bezeichnet wird, umfasst das Senden von 
+HTTP-Anfragen mit dem [`HfApi`] Client. Schauen wir uns die Vor- und Nachteile jeder 
+Methode an.
+
+## Repository: Der historische git-basierte Ansatz
+
+Ursprünglich wurde `huggingface_hub` größtenteils um die [`Repository`] Klasse herum 
+entwickelt. Sie bietet Python-Wrapper für gängige git-Befehle wie `"git add"`, `"git commit"`, 
+`"git push"`, `"git tag"`, `"git checkout"` usw.
+
+Die Bibliothek hilft auch beim Festlegen von Zugangsdaten und beim Tracking von großen 
+Dateien, die in Machine-Learning-Repositories häufig verwendet werden. Darüber hinaus 
+ermöglicht die Bibliothek das Ausführen ihrer Methoden im Hintergrund, was nützlich ist, 
+um Daten während des Trainings hochzuladen.
+
+Der Hauptvorteil bei der Verwendung einer [`Repository`] besteht darin, dass Sie eine 
+lokale Kopie des gesamten Repositorys auf Ihrem Computer pflegen können. Dies kann jedoch 
+auch ein Nachteil sein, da es erfordert, diese lokale Kopie ständig zu aktualisieren und 
+zu pflegen. Dies ähnelt der traditionellen Softwareentwicklung, bei der jeder Entwickler 
+eine eigene lokale Kopie pflegt und Änderungen überträgt, wenn an einer Funktion 
+gearbeitet wird. Im Kontext des Machine Learning ist dies jedoch nicht immer erforderlich, 
+da Benutzer möglicherweise nur Gewichte für die Inferenz herunterladen oder Gewichte von 
+einem Format in ein anderes konvertieren müssen, ohne das gesamte Repository zu klonen.
+
+## HfApi: Ein flexibler und praktischer HTTP-Client
+
+Die [`HfApi`] Klasse wurde entwickelt, um eine Alternative zu lokalen Git-Repositories 
+bereitzustellen, die besonders bei der Arbeit mit großen Modellen oder Datensätzen 
+umständlich zu pflegen sein können. Die [`HfApi`] Klasse bietet die gleiche Funktionalität 
+wie git-basierte Ansätze, wie das Herunterladen und Hochladen von Dateien sowie das 
+Erstellen von Branches und Tags, jedoch ohne die Notwendigkeit eines lokalen Ordners, der 
+synchronisiert werden muss.
+
+Zusätzlich zu den bereits von `git` bereitgestellten Funktionen bietet die [`HfApi`] 
+Klasse zusätzliche Features wie die Möglichkeit, Repositories zu verwalten, Dateien mit 
+Caching für effiziente Wiederverwendung herunterzuladen, im Hub nach Repositories und 
+Metadaten zu suchen, auf Community-Funktionen wie Diskussionen, Pull Requests und 
+Kommentare zuzugreifen und Spaces-Hardware und Geheimnisse zu konfigurieren.
+
+## Was sollte ich verwenden ? Und wann ?
+
+Insgesamt ist der **HTTP-basierte Ansatz in den meisten Fällen die empfohlene Methode zur Verwendung von** 
+`huggingface_hub`. Es gibt jedoch einige Situationen, in denen es vorteilhaft sein kann, 
+eine lokale Git-Kopie (mit [`Repository`]) zu pflegen:
+- Wenn Sie ein Modell auf Ihrem Computer trainieren, kann es effizienter sein, einen 
+herkömmlichen git-basierten Workflow zu verwenden und regelmäßige Updates zu pushen. 
+[`Repository`] ist für diese Art von Situation mit seiner Fähigkeit zur Hintergrundarbeit optimiert.
+- Wenn Sie große Dateien manuell bearbeiten müssen, ist `git` die beste Option, da es nur 
+die Differenz an den Server sendet. Mit dem [`HfAPI`] Client wird die gesamte Datei bei 
+jeder Bearbeitung hochgeladen. Beachten Sie jedoch, dass die meisten großen Dateien binär 
+sind und daher sowieso nicht von Git-Diffs profitieren.
+
+Nicht alle Git-Befehle sind über [`HfApi`] verfügbar. Einige werden vielleicht nie 
+implementiert, aber wir bemühen uns ständig, die Lücken zu schließen und zu verbessern. 
+Wenn Sie Ihren Anwendungsfall nicht abgedeckt sehen, öffnen Sie bitte [ein Issue auf 
+Github](https://github.com/huggingface/huggingface_hub)! Wir freuen uns über Feedback, um das 🤗-Ökosystem mit und für unsere Benutzer aufzubauen.

docs/source/de/index.md

@@ -16,11 +16,6 @@ In der [Kurzanleitung](quick-start) der `huggingface_hub` Bibliothek erfahren Si
       <p class="text-gray-700">Praktische Leitfäden, um ein bestimmtes Ziel zu erreichen. Durchstöbern Sie diese Anleitungen, um zu erfahren, wie Sie mit huggingface_hub echte Herausforderungen meistern können.</p>
     </a>
 
-    <a class="!no-underline border dark:border-gray-700 p-5 rounded-lg shadow hover:shadow-lg" href="./package_reference/overview">
-      <div class="w-full text-center bg-gradient-to-br from-purple-400 to-purple-500 rounded-lg py-1.5 font-semibold mb-5 text-white text-lg leading-relaxed">Referenz</div>
-      <p class="text-gray-700">Umfassende und technische Beschreibung der Klassen und Methoden von huggingface_hub.</p>
-    </a>
-
     <a class="!no-underline border dark:border-gray-700 p-5 rounded-lg shadow hover:shadow-lg" href="./concepts/git_vs_http">
       <div class="w-full text-center bg-gradient-to-br from-pink-400 to-pink-500 rounded-lg py-1.5 font-semibold mb-5 text-white text-lg leading-relaxed">Konzeptionelle Leitfäden</div>
       <p class="text-gray-700">Methodische Erklärungen zum Aufbau eines besseren Verständnisses der Huggingface_hub-Philosophie.</p>
@@ -29,6 +24,11 @@ In der [Kurzanleitung](quick-start) der `huggingface_hub` Bibliothek erfahren Si
   </div>
 </div>
 
+<!-- <a class="!no-underline border dark:border-gray-700 p-5 rounded-lg shadow hover:shadow-lg" href="./package_reference/overview">
+  <div class="w-full text-center bg-gradient-to-br from-purple-400 to-purple-500 rounded-lg py-1.5 font-semibold mb-5 text-white text-lg leading-relaxed">Referenz</div>
+  <p class="text-gray-700">Umfassende und technische Beschreibung der Klassen und Methoden von huggingface_hub.</p>
+</a> -->
+
 <!-- 
 <a class="!no-underline border dark:border-gray-700 p-5 rounded-lg shadow hover:shadow-lg" href="./tutorials/overview"
   ><div class="w-full text-center bg-gradient-to-br from-blue-400 to-blue-500 rounded-lg py-1.5 font-semibold mb-5 text-white text-lg leading-relaxed">Tutorials</div>

docs/source/en/_toctree.yml

@@ -24,6 +24,8 @@
       title: Inference
     - local: guides/community
       title: Community Tab
+    - local: guides/collections
+      title: Collections
     - local: guides/manage-cache
       title: Cache
     - local: guides/model-cards
@@ -68,6 +70,8 @@
       title: Repo Cards and Repo Card Data
     - local: package_reference/space_runtime
       title: Space runtime
+    - local: package_reference/collections
+      title: Collections
     - local: package_reference/tensorboard
       title: TensorBoard logger
     - local: package_reference/webhooks_server

docs/source/en/guides/collections.md

@@ -0,0 +1,187 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
+# Collections
+
+A collection is a group of related items on the Hub (models, datasets, Spaces, papers) that are organized together on the same page. Collections are useful for creating your own portfolio, bookmarking content in categories, or presenting a curated list of items you want to share. Check out this [guide](https://huggingface.co/docs/hub/collections) to understand in more detail what collections are and how they look on the Hub.
+
+You can directly manage collections in the browser, but in this guide, we will focus on how to manage it programmatically.
+
+## Fetch a collection
+
+Use [`get_collection`] to fetch your collections or any public ones. You must have the collection's *slug* to retrieve a collection. A slug is an identifier for a collection based on the title and a unique ID. You can find the slug in the URL of the collection page.
+
+<div class="flex justify-center">
+    <img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hfh_collection_slug.png"/>
+</div>
+
+Let's fetch the collection with, `"TheBloke/recent-models-64f9a55bb3115b4f513ec026"`:
+
+```py
+>>> from huggingface_hub import get_collection
+>>> collection = get_collection("TheBloke/recent-models-64f9a55bb3115b4f513ec026")
+>>> collection
+Collection: { 
+  {'description': "Models I've recently quantized.',
+   'items': [...],
+   'last_updated': datetime.datetime(2023, 9, 21, 7, 26, 28, 57000, tzinfo=datetime.timezone.utc),
+   'owner': 'TheBloke',
+   'position': 1,
+   'private': False,
+   'slug': 'TheBloke/recent-models-64f9a55bb3115b4f513ec026',
+   'theme': 'green',
+   'title': 'Recent models'}
+}
+>>> collection.items[0]
+CollectionItem: { 
+  {'item_object_id': '6507f6d5423b46492ee1413e',
+   'author': 'TheBloke',
+   'item_id': 'TheBloke/TigerBot-70B-Chat-GPTQ',
+   'item_type': 'model',
+   'lastModified': '2023-09-19T12:55:21.000Z',
+   'position': 0,
+   'private': False,
+   'repoType': 'model'
+   (...)
+  }
+}
+```
+
+The [`Collection`] object returned by [`get_collection`] contains:
+- high-level metadata: `slug`, `owner`, `title`, `description`, etc.
+- a list of [`CollectionItem`] objects; each item represents a model, a dataset, a Space, or a paper.
+
+All collection items are guaranteed to have:
+- a unique `item_object_id`: this is the id of the collection item in the database
+- an `item_id`: this is the id on the Hub of the underlying item (model, dataset, Space, paper); it is not necessarily unique, and only the `item_id`/`item_type` pair is unique
+- an `item_type`: model, dataset, Space, paper
+- the `position` of the item in the collection, which can be updated to reorganize your collection (see [`update_collection_item`] below)
+
+A `note` can also be attached to the item. This is useful to add additional information about the item (a comment, a link to a blog post, etc.). The attribute still has a `None` value if an item doesn't have a note.
+
+In addition to these base attributes, returned items can have additional attributes depending on their type: `author`, `private`, `lastModified`, `gated`, `title`, `likes`, `upvotes`, etc. None of these attributes are guaranteed to be returned.
+
+## Create a new collection
+
+Now that we know how to get a [`Collection`], let's create our own! Use [`create_collection`] with a title and description. To create a collection on an organization page, pass `namespace="my-cool-org"` when creating the collection. Finally, you can also create private collections by passing `private=True`.
+
+```py
+>>> from huggingface_hub import create_collection
+
+>>> collection = create_collection(
+...     title="ICCV 2023",
+...     description="Portfolio of models, papers and demos I presented at ICCV 2023",
+... )
+```
+
+It will return a [`Collection`] object with the high-level metadata (title, description, owner, etc.) and an empty list of items. You will now be able to refer to this collection using it's `slug`.
+
+```py
+>>> collection.slug
+'owner/iccv-2023-15e23b46cb98efca45'
+>>> collection.title
+"ICCV 2023"
+>>> collection.owner
+"username"
+>>> collection.url
+'https://huggingface.co/collections/owner/iccv-2023-15e23b46cb98efca45'
+```
+
+## Manage items in a collection
+
+Now that we have a [`Collection`], we want to add items to it and organize them.
+
+### Add items
+
+Items have to be added one by one using [`add_collection_item`]. You only need to know the `collection_slug`, `item_id` and `item_type`. Optionally, you can also add a `note` to the item (500 characters maximum).
+
+```py
+>>> from huggingface_hub import create_collection, add_collection_item
+
+>>> collection = create_collection(title="OS Week Highlights - Sept 18 - 24", namespace="osanseviero")
+>>> collection.slug
+"osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80"
+
+>>> add_collection_item(collection.slug, item_id="coqui/xtts", item_type="space")
+>>> add_collection_item(
+...     collection.slug,
+...     item_id="warp-ai/wuerstchen",
+...     item_type="model",
+...     note="Würstchen is a new fast and efficient high resolution text-to-image architecture and model"
+... )
+>>> add_collection_item(collection.slug, item_id="lmsys/lmsys-chat-1m", item_type="dataset")
+>>> add_collection_item(collection.slug, item_id="warp-ai/wuerstchen", item_type="space") # same item_id, different item_type
+```
+
+If an item already exists in a collection (same `item_id`/`item_type` pair), an HTTP 409 error will be raised. You can choose to ignore this error by setting `exists_ok=True`.
+
+### Add a note to an existing item
+
+You can modify an existing item to add or modify the note attached to it using [`update_collection_item`]. Let's reuse the example above:
+
+```py
+>>> from huggingface_hub import get_collection, update_collection_item
+
+# Fetch collection with newly added items
+>>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80"
+>>> collection = get_collection(collection_slug)
+
+# Add note the `lmsys-chat-1m` dataset
+>>> update_collection_item(
+...     collection_slug=collection_slug,
+...     item_object_id=collection.items[2].item_object_id,
+...     note="This dataset contains one million real-world conversations with 25 state-of-the-art LLMs.",
+... )
+```
+
+### Reorder items
+
+Items in a collection are ordered. The order is determined by the `position` attribute of each item. By default, items are ordered by appending new items at the end of the collection. You can update the order using [`update_collection_item`] the same way you would add a note.
+
+Let's reuse our example above:
+
+```py
+>>> from huggingface_hub import get_collection, update_collection_item
+
+# Fetch collection
+>>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80"
+>>> collection = get_collection(collection_slug)
+
+# Reorder to place the two `Wuerstchen` items together
+>>> update_collection_item(
+...     collection_slug=collection_slug,
+...     item_object_id=collection.items[3].item_object_id,
+...     position=2,
+... )
+```
+
+### Remove items
+
+Finally, you can also remove an item using [`delete_collection_item`].
+
+```py
+>>> from huggingface_hub import get_collection, update_collection_item
+
+# Fetch collection
+>>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80"
+>>> collection = get_collection(collection_slug)
+
+# Remove `coqui/xtts` Space from the list
+>>> delete_collection_item(collection_slug=collection_slug, item_object_id=collection.items[0].item_object_id)
+```
+
+## Delete collection
+
+A collection can be deleted using [`delete_collection`].
+
+<Tip warning={true}>
+
+This is a non-revertible action. A deleted collection cannot be restored.
+
+</Tip>
+
+```py
+>>> from huggingface_hub import delete_collection
+>>> collection = delete_collection("username/useless-collection-64f9a55bb3115b4f513ec026", missing_ok=True)
+```

docs/source/en/guides/overview.md

@@ -73,6 +73,15 @@ Take a look at these guides to learn how to use huggingface_hub to solve real-wo
       </p>
     </a>
 
+    <a class="!no-underline border dark:border-gray-700 p-5 rounded-lg shadow hover:shadow-lg"
+       href="./collections">
+      <div class="w-full text-center bg-gradient-to-br from-indigo-400 to-indigo-500 rounded-lg py-1.5 font-semibold mb-5 text-white text-lg leading-relaxed">
+        Collections
+      </div><p class="text-gray-700">
+        How to programmatically build collections?
+      </p>
+    </a>
+
     <a class="!no-underline border dark:border-gray-700 p-5 rounded-lg shadow hover:shadow-lg"
        href="./manage-cache">
       <div class="w-full text-center bg-gradient-to-br from-indigo-400 to-indigo-500 rounded-lg py-1.5 font-semibold mb-5 text-white text-lg leading-relaxed">

docs/source/en/package_reference/collections.md

@@ -0,0 +1,24 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
+# Managing collections
+
+Check out the [`HfApi`] documentation page for the reference of methods to manage your Space on the Hub.
+
+- Get collection content: [`get_collection`]
+- Create new collection: [`create_collection`]
+- Update a collection: [`update_collection_metadata`]
+- Delete a collection: [`delete_collection`]
+- Add an item to a collection: [`add_collection_item`]
+- Update an item in a collection: [`update_collection_item`]
+- Remove an item from a collection: [`delete_collection_item`]
+
+
+### Collection
+
+[[autodoc]] Collection
+
+### CollectionItem
+
+[[autodoc]] CollectionItem

setup.py

@@ -13,7 +13,7 @@ def get_version() -> str:
 
 install_requires = [
     "filelock",
-    "fsspec",
+    "fsspec>=2023.5.0",
     "requests",
     "tqdm>=4.42.1",
     "pyyaml>=5.1",