Rym w tytule samouczka niezamierzony.

Ten samouczek to instrukcja pracy z moim skryptem Pythona, pozwalającym tworzyć wykresy i grafy powiązań dla odpisów z Krajowego Rejestru Sądowego.

Aktualizacja 15.02.2022 r.: Dodałem do skryptu możliwość tworzenia grafów powiązań między firmami. Jeśli chcecie z niej skorzystać, zachęcam do pobrania nowej wersji skryptu.

Aktualizacja 18.02.2022 r.: Poprawiłem parę błędów, komfort użytkowania przy odpalaniu skryptu przez podwójne kliknięcie, dodałem możliwość układania grafów od lewej do prawej.

Linki do różnych wersji skryptu:

Zachęcam, żeby zawsze korzystać z najnowszej :smile:

Wymagania

Zanim zaczniemy cokolwiek robić, pobieramy Pythona z oficjalnej strony. Instalując go, pamiętamy – przynajmniej na Windowsie – żeby zaznaczyć opcję zainstalowania dodatków: pip i IDLE.

Pierwsze kroki z Pythonem opisałem w osobnym samouczku. Zachęcam zainteresowanych do lektury.

Moduły Pythona

Skrypt potrzebuje do działania trzech zewnętrznych modułów. Dlatego najpierw włączamy naszą zaufaną konsolę
(jak PowerShell w przypadku Windowsa; można go znaleźć w menu Start albo nacisnąć Przycisk z ikoną Windowsa+X, a potem I jak inwigilacja).

Następnie pobieramy co trzeba:

  1. Biblioteki BeautifulSoup oraz lxml do grzebania w XML-u.
    Instalujemy je, wpisując w konsolce i potwierdzając Enterem:

    pip install beautifulsoup4

    A także:

    pip install lxml

  2. Bibliotekę Matplotlib do tworzenia wykresów.

    Ważne! Kiedy testowałem skrypt na Windowsie 10, nowsza wersja nie działała. Zgodnie z pewną odpowiedzią z forum pomaga zainstalowanie nieco starszej, 3.3.1. Dlatego na Windowsie wpisujemy:

    pip install matplotlib==3.3.1

    A na innych systemach operacyjnych możemy zamiast tego brać najnowszą:

    pip install matplotlib

Poppler

Poppler to biblioteka służąca do pracy z plikami PDF. Mój skrypt wykorzystuje ją do wyciągania z nich tekstu.
Nie jest to niestety moduł Pythona, tylko rzecz napisana w innym języku, więc jej pobranie wymaga paru dodatkowych kroków. Ale łatwych, więc bez obaw :smile:

  • Na Windowsie:

    Pobieracie ZIP-a z przygotowanymi plikami z tej strony i go rozpakowujecie w tym samym folderze, w którym trzymacie skrypt.

Da się też zainstalować Popplera w miejscu, w którym będzie łatwiej dostępny dla innych programów. Ale to już zostawiam chętnym.

Uwaga

Gdyby podczas odpalania skryptu wyświetlało Wam komunikat o brakującym pliku MSVCP140.dll, to go pobieracie z oficjalnej strony Microsoftu, klikacie i instalujecie (podlinkowałem wersję 64-bitową, bo zapewne taki macie system).
Windows to jednak lubi rzucać kłody pod nogi :roll_eyes:

  • Na Linuksie:

    Postępujecie zgodnie z instrukcjami z tej odpowiedzi.
    Cytując je (na wypadek gdyby link padł), wpisujecie w konsolę:

    sudo apt-get install -y poppler-utils

  • Na OSX (komputery Apple):

    Nie sprawdzałem, ale podobno w oficjalnych źródłach ma elegancko przygotowanego Popplera. Pobieracie go i instalujecie.

Kiedy już macie wszystkie potrzebne moduły, skrypt oraz PDF-y w jednym miejscu, to możecie produkować wykresy do woli.

Graphviz / dot

(opcjonalny; tylko wtedy, jeśli chcemy rysować grafy powiązań między firmami).

Instrukcje instalacji znajdziemy na oficjalnej stronie.

Instrukcje korzystania

W najprostszym przypadku po prostu odpalacie skrypt, zdając się na domyślne ustawienia – na przykład otwierając go w domyślnym edytorze IDLE i naciskając F5. Albo w dowolny inny sposób.

Na samym końcu skryptu znajdziecie parę ustawień, które możecie zmienić, żeby dostosować swoje wykresy i grafy.

Gdybyście coś zmienili w domyślnych ustawieniach i wyskakiwałby Wam błąd (zapewne gatunku SyntaxError), to znaczy że omyłkowo usunęliście jakieś ważne znaki albo spacje.
W takim wypadku najlepiej pobierzcie mój skrypt od nowa, a zmiany tym razem wprowadzajcie bardzo ostrożnie.

Tworzenie wykresów

Skrypt za każdym razem wrzuca pliki z wykresami do folderu Wykresy, w formacie obrazków JPG (po jednym dla każdego odpisu).

Aby zmienić domyślne ustawienia, ustawiacie inne wartości zmiennych na końcu skryptu (oznaczone odpowiednimi komentarzami).

Pierwszą z tych zmiennych jest folder, w którym skrypt wypatruje plików PDF z KRS-u. Jeśli nic tam nie wpiszecie, będzie szukał w tym samym folderze, w którym go odpalacie:

folder = ""

Jeśli natomiast wpiszecie między cudzysłowami nazwę jakiegoś konkretnego folderu (albo wkleicie całą ścieżkę do niego), to skrypt poszuka plików z odpisami właśnie tam.

Kolejne z ustawień to kategorie, dla których skrypt stworzy wykresy. Domyślnie macie:

info = ['nazwa','adres','zarząd','wspólnicy']

Nie możecie dopisać własnych zmyślonych nazw kategorii, musicie wybierać spośród tych czterech. Ale możecie zmieniać ich kolejność albo usuwać dowolne z nich.
Przykładowo, wpisując info=['adres','wspólnicy'], otrzymacie wykres jedynie dla zmian adresu i wspólników/udziałowców.

Ostatnie z ustawień to wymiary wykresu:

width, height = 9, 20

Liczba 9 odnosi się tu do szerokości, a 20 do wysokości. To wymiary w calach.
W praktyce możecie je sobie dowolnie zmieniać, gdyby wykres był nieczytelny, a etykiety na siebie nachodziły (taki problem pojawia się zwłaszcza przy spółkach, w których dużo się dzieje).

Po wprowadzeniu takiej zmiany odpalamy ponownie skrypt i możemy się cieszyć wykresem w nowych wymiarach.

Tworzenie grafów powiązań

W najnowszej wersji skryptu ta opcja jest domyślnie włączona. Więc po prostu odpalacie skrypt, a w osobnym folderze Grafy powinny pojawić się dwa pliki:

  • Plik SVG z grafem powiązań;
  • Plik GV.
    (Bardziej zaawansowani użytkownicy mogą go edytować, żeby na przykład wyróżnić niektóre połączenia, zakryć część danych itp. Po edycji trzeba własnoręcznie użyć na pliku programu dot, żeby otrzymać zmieniony graf).

Jeśli chcecie zmienić domyślne ustawienia, to w przypadku grafów macie następujące zmienne:

ONLY_GRAPH_KRS_COMPANIES = False

Przy tym ustawieniu na Waszym grafie będą widoczne wszystkie powiązania; również ze spółkami oraz osobami prywatnymi, dla których nie macie odpisów. Takie powiązania będą oznaczone czerwonawym kolorem.

Uwaga: skrypt na razie nie jest w stanie odróżnić firm od osób fizycznych.

Jeśli chcecie wyświetlić jedynie powiązania dla tych firm, dla których macie odpisy, to zmieniacie wartość z False na True.

ARRANGE_GRAPH_LEFT_TO_RIGHT = False

Graf domyślnie jest układany od góry do dołu. Jednak czasami jest to nieczytelne i wymaga przewijania ekranu w bok (zwłaszcza gdy mamy „płytką strukturę” z wieloma udziałowcami na pierwszym szczeblu).

W takiej sytuacji zmieniamy wartość z False na True i odpalamy skrypt ponownie. Powinno być czytelniej.

Opcje zaawansowane

Użytkownicy zaawansowani i umiejący w Pythona mogą, począwszy od drugiej wersji skryptu, dodawać własne funkcje modyfikujące dane przed wizualizacją:

pre_graph_transform = None
pre_timeline_transform = None

pre_timeline_transform z założenia działa na danych, z których stworzymy wykresy, a pre_graph_transform – na tych, z których powstają grafy.
Każdy z nich pracuje na kopii danych, tuż przed wizualizacją, i nie zmienia ich na stałe.

Filtry są przydatne, jeśli chcemy coś zmienić w danych tuż przed wizualizacją – na przykład zamaskować niektóre nazwiska, odfiltrować część informacji itp.

Tworząc filtry, pamiętajcie:

  • Na wejściu macie listę krotek z danymi o firmach (zmienna companies);
  • Każda krotka ma postać (krs_id, name, last_date, events) – kolejno numer KRS firmy, jej aktualną nazwę, najpóźniejszą znaną nam datę oraz listę zdarzeń z jej „życia”. Każde ze zdarzeń to klasa KrsEvent, więc to jej się przyjrzyjcie w razie potrzeby.
  • Na wyjściu Wasza funkcja również powinna zwracać listę 4-elementowych krotek, tylko że odpowiednio zmodyfikowaną.

Jeśli chcecie zobaczyć przykład filtra, możecie spojrzeć na moją funkcję replace_names_with_original, obecną w skrypcie.
Domyślnie nie jest używana, ale skorzystałem z niej, tworząc wpis na bloga. Robi z danymi następujące rzeczy:

  • Zmienia nazwę firmy (środkowe pole każdej krotki), biorąc z listy zdarzeń nazwę najstarszą.
  • Skraca tę nazwę, a także nazwy wszystkich innych firm/wspólników ze zdarzeń, usuwając z nich tekst w stylu SP. Z O.O..

Ograniczenia

Skrypt do tej pory mi działał, ale na pewno istnieją pliki, z którymi gorzej sobie poradzi. Najlepiej go używać do wstępnego wyłapania ciekawych rzeczy, a potem je weryfikować, zaglądając prosto do PDF-a z odpisem.

No i, na koniec, pamiętajmy że mamy również pewne ograniczenia związane nie tylko ze skryptem, lecz z KRS-em jako takim:

  • Nie będzie nam pokazywało wspólników/udziałowców w przypadku niektórych spółek (na przykład akcyjnych, bo tam akcjonariusze często się zmieniają i może ich być bardzo wielu).
  • Nawet jeśli mamy ładną spółkę z o.o., to według tego wpisu o anonimowych spółkach KRS nie udostępnia listy wspólników mających poniżej 5% udziałów.
  • Odpisy z KRS-u nie nadają się do wyłapywania wszystkich powiązań danej firmy, ponieważ pokazują tylko jedną stronę relacji (tzn. kto był w danej firmie udziałowcem; nie widzimy natomiast, czy ta firma była udziałowcem w czymś innym).

Miłego wyłapywania firmowych ciekawostek!