omnis-py

Biblioteka Python do obsługi API Ex Libris Primo (sieć OMNIS) oraz narzędzie CLI do zarządzania kontami bibliotecznymi.

Opis (PL)

omnis-py to biblioteka umożliwiająca programistyczny dostęp do kont czytelnika w bibliotekach korzystających z systemu Ex Libris Primo (w Polsce działających głównie w ramach sieci OMNIS).

Główne funkcjonalności

• Autentykacja: Logowanie do systemów bibliotecznych przy użyciu numeru karty i hasła.
• Wypożyczenia: Pobieranie listy aktywnych wypożyczeń wraz ze szczegółami (data zwrotu, autor, tytuł, filia).
• Informacje o użytkowniku: Pobieranie stanu konta, liczby wypożyczeń, rezerwacji oraz naliczonych kar.
• Prolongata: Możliwość przedłużania terminu zwrotu książek.
• Narzędzie CLI: Wygodna aplikacja terminalowa do monitorowania wielu kont na raz.

Obsługiwane biblioteki (znane tenany)

Biblioteka jest uniwersalna i obsługuje m.in.:

• Biblioteka Raczyńskich (Poznań)
• Biblioteka Narodowa (Warszawa)
• Biblioteka UAM (Poznań)
• Dolnośląska Biblioteka Publiczna (Wrocław)
• Uniwersytet Jagielloński (Kraków)
• Uniwersytet Mikołaja Kopernika (Toruń)
• Wojewódzka Biblioteka Publiczna (Kielce)
• Koszalińska Biblioteka Publiczna
• Książnica Zamojska
• ...oraz każdą inną bibliotekę Primo po podaniu jej adresu URL i kodu instytucji.

Instalacja

pip install omnis-py

Dla narzędzia CLI zalecane jest użycie pipx:

pipx install omnis-py

Użycie CLI

Po instalacji dostępne jest polecenie omnis-cli.

Przy pierwszym uruchomieniu program poprowadzi Cię przez kreator dodawania konta. Konfiguracja jest przechowywana w ~/.config/omnis-py/config.yaml.

• omnis-cli - wyświetla podsumowanie dla wszystkich kont i listę książek pogrupowaną według filii.
• omnis-cli --add - dodaje nowe konto do konfiguracji.
• omnis-cli --renew - próbuje przedłużyć wszystkie wypożyczenia oznaczone jako odnawialne dla skonfigurowanych kont przed pobraniem danych. Używaj ostrożnie; operacja wykona się bez dodatkowego potwierdzenia.
• omnis-cli --search "tytuł lub fragment" - wyszukuje książki w katalogu (na koncie pierwszej skonfigurowanej biblioteki), grupując wyniki wg tytułu i pokazując wszystkie wydania/wersje osobno wraz ze statusem dostępności w poszczególnych filiach (dostępna / wypożyczona do dnia).
• omnis-cli --search "..." --branch "nazwa filii" - jak wyżej, ale ogranicza wyniki do filii, których nazwa zawiera podany fragment (bez rozróżniania wielkości liter).
• omnis-cli --branches - pokazuje katalog filii Biblioteki Raczyńskich (adres, godziny otwarcia, telefon, link do Google Maps). Nie wymaga skonfigurowanego konta - dane pochodzą bezpośrednio ze strony bracz.edu.pl. Działa wyłącznie dla Biblioteki Raczyńskich.
• omnis-cli --branches --branch "Filia 35" - jak wyżej, ograniczone do filii, których nazwa zawiera podany fragment.

Przykład wyszukiwania krok po kroku (cały cykl książek, z priorytetem konkretnych filii): docs/examples/plomien-i-krzyz.md.

Description (EN)

omnis-py is a Python library providing programmatic access to patron accounts in libraries using the Ex Libris Primo system (widely used in Poland under the OMNIS network).

Key Features

• Authentication: Login using card number and password.
• Loans: Fetch active loans with details (due date, author, title, branch).
• User Info: Get account status, number of loans, requests, and fines.
• Renewal: Support for renewing book loan terms.
• CLI Tool: A convenient terminal application to monitor multiple accounts at once.

Supported Libraries

The library is generic and supports various institutions including:

• Raczyński Library (Poznań)
• National Library of Poland (Warszawa)
• Adam Mickiewicz University Library (Poznań)
• Lower Silesian Public Library (Wrocław)
• Jagiellonian University (Kraków)
• Nicolaus Copernicus University (Toruń)
• ...and any other Primo library by providing its URL and institution code.

Installation

pip install omnis-py

For the CLI tool, using pipx is recommended:

pipx install omnis-py

CLI Usage

Once installed, the omnis-cli command becomes available.

On first run, it will guide you through adding an account. Configuration is stored in ~/.config/omnis-py/config.yaml.

• omnis-cli - shows a summary for all accounts and a book list grouped by branch.
• omnis-cli --add - adds a new account to the configuration.
• omnis-cli --renew - attempts to renew all loans marked as renewable for configured accounts before fetching data. Use with caution; this action runs without an additional confirmation.
• omnis-cli --search "title or keyword" - searches the catalog (using the first configured account), grouping results by title and showing every edition/version separately along with per-branch availability (available / borrowed until date).
• omnis-cli --search "..." --branch "branch name" - as above, but limited to branches whose name contains the given text (case-insensitive).
• omnis-cli --branches - shows the Biblioteka Raczyńskich branch directory (address, opening hours, phone, Google Maps link). No account required - data comes directly from bracz.edu.pl. Works for Biblioteka Raczyńskich only.
• omnis-cli --branches --branch "Filia 35" - as above, limited to branches whose name contains the given text.

Home Assistant

Istnieje również integracja dla Home Assistant korzystająca z tej biblioteki: omnis-ha.

There is also a Home Assistant integration using this library: omnis-ha.

License

MIT