Git scraping: методика бесплатного хостинга не совсем статических сайтов04.02.2023 10:02

Одна из таких проблем: правильный выбор скорости (BPM) и тональности (Key) для новой композиции. Этот вопрос каждый раз встаёт перед артистом при создании нового проекта в FL Studio или Cubase. Для электронной танцевальной музыки неверный выбор этих значений может вылиться даже в сложности с попаданием работы на лейбл или в микс. Подробнее об этом я рассказал здесь.

С первого взгляда кажется, что это должно решаться классическим «загугливанием»: просто введи в поиск «tech house bpm» и получи результат, но это не совсем так. Значения скоростей и тональностей являются трендами. А тренды имеют свойство меняться. Поисковая выдача довольно часто может становиться неактуальной в этом случае.

В своё время я нашёл такой способ решения этой проблемы:

1. Найти список свежих наилучших треков жанра, в котором я работаю. Для меня авторитетным всегда был чарт Beatport Top 100

2. Получить значения скоростей и тональностей для каждой композиции чарта. Такие ресурсы, как Beatport и Spotify, предоставляют подобную информацию бесплатно

3. Подсчитав полученные значения, составить отчёт, который бы показывал список скоростей и тональностей, отсортированный по популярности

4. Выбрать одно из топовых значений для своей следующей композиции

Именно эту последовательность действий я и собираюсь автоматизировать в данной статье, но не для одного, а для всех жанров, представленных на Beatport.

Создадим новое виртуальное окружение:

python -m venv venv

Активируем его:

venv\Scripts\activate

Добавим зависимости, создав requirements.txt:

# Асинхронные HTTP-запросы
aiohttp>=3
# Генерация статических веб-страниц
Jinja2>=3

Загрузим зависимости:

python -m pip install -r requirements.txt

Инициализируем наш пакет в Cargo:

cargo init

Добавим зависимости, отредактировав Cargo.toml:

...
[dependencies]
# Среда выполнения асинхронного кода
tokio = { version = "1", features = ["full"] }
# Асинхронные HTTP-запросы
reqwest = { version = "0.11", features = ["json"] }
# Генерация статических веб-страниц
tera = "1"
# Сериализация
serde = { version = "1", features = ["derive"] }
# Обработка ошибок
anyhow = "1"

Загрузим зависимости и убедимся, что подготовка пройдена успешно:

cargo run

import asyncio
from typing import List

import extract
import load
import model
import transform

BEATPORT_URL = "https://www.beatport.com"


async def main():
    # Получаем главную страницу Beatport
    main_page: str = await extract.page(BEATPORT_URL)

    # Достаём из неё ссылки на Top 100 страницы для каждого жанра
    genre_top_100_urls: List[str] = transform.main_page_to_genre_top_100_urls(main_page)

    # Конкурентно получаем содержимое Top 100 страниц для каждого жанра
    genre_top_100_pages: List[str] = await extract.multiple_pages(genre_top_100_urls)

    # Анализируем Top 100 страницы, составляя отчёты для каждого музыкального жанра
    genre_reports: List[model.Report] = transform.genre_top_100_pages_to_reports(
        genre_top_100_pages
    )

    # Отображаем наши отчёты в виде статической веб-страницы
    load.build(genre_reports)


if __name__ == "__main__":
    asyncio.run(main())

mod extract;
mod load;
mod model;
mod transform;

use anyhow::Result;

const BEATPORT_URL: &str = "https://www.beatport.com";

#[tokio::main]
async fn main() -> Result<()> {
    // Получаем главную страницу Beatport
    let main_page: String = extract::page(BEATPORT_URL).await?;

    // Достаём из неё ссылки на Top 100 страницы для каждого жанра
    let genre_top_100_urls: Vec<&str> = transform::main_page_to_genre_top_100_urls(&main_page)?;

    // Конкурентно получаем содержимое Top 100 страниц для каждого жанра
    let genre_top_100_pages: Vec = extract::multiple_pages(&genre_top_100_urls).await?;

    // Анализируем Top 100 страницы, составляя отчёты для каждого музыкального жанра
    let genre_reports: model::ReportVec =
        transform::genre_top_100_pages_to_reports(&genre_top_100_pages)?;

    // Отображаем наши отчёты в виде статической веб-страницы
    load::build(genre_reports).await
}

from dataclasses import dataclass
from typing import List, Tuple


# Аналитика по музыкальному жанру
@dataclass
class Report:
    # Название музыкального жанра
    genre: str

    # Наиболее популярные значения скоростей (BPM): (количество, значение)
    bpm_chart: List[Tuple[int, int]]

    # Наиболее популярные значения тональностей (Key): (количество, значение)
    # Вместо str следует использовать Enum, но это бы усложнило пример
    key_chart: List[Tuple[int, str]]

use serde::Serialize;

// Аналитика по музыкальному жанру
#[derive(Serialize)]
pub struct Report {
    // Название музыкального жанра
    pub genre: String,

    // Наиболее популярные значения скоростей (BPM): (количество, значение)
    pub bpm_chart: Vec<(usize, u16)>,

    // Наиболее популярные значения тональностей (Key): (количество, значение)
    // Вместо String следует использовать Enum, но это бы усложнило пример
    pub key_chart: Vec<(usize, String)>,
}

// Tera будет выдавать ошибку, если мы не обернём вектор отчетов
#[derive(Serialize)]
pub struct ReportVec {
    pub reports: Vec,
}

import asyncio
from typing import List, Optional

import aiohttp


async def page(url: str) -> Optional[str]:
    # Для повторяющихся запросов рекомендуется переиспользовать одну сессию aiohttp.ClientSession
    # Подробнее: https://docs.aiohttp.org/en/stable/client_quickstart.html
    # Но это бы усложнило пример
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as resp:
            return await resp.text()


# Чтобы понять, что здесь происходит, вы можете ознакомиться с документацией asyncio:
# https://docs.python.org/3/library/asyncio.html
async def multiple_pages(urls: List[str]) -> Optional[List[str]]:
    # Конкурентно вызываем page() для каждой входящей ссылки
    handles = list(map(lambda x: asyncio.create_task(page(x)), urls))

    pages = []
    # Получаем результаты в список
    for handle in handles:
        pages.append(await handle)

    return pages

use anyhow::Result;

pub async fn page(url: &str) -> Result {
    // Для повторяющихся запросов рекомендуется переиспользовать один клиент reqwest::Client
    // Подробнее: https://docs.rs/reqwest/latest/reqwest/
    // Конкурентный GET можно было бы реализовать через Client.clone(), но это бы усложнило пример
    // https://users.rust-lang.org/t/reqwest-http-client-fails-when-too-much-concurrency/55644
    let response = reqwest::get(url).await?.text().await?;
    Ok(response)
}

// Чтобы понять, что здесь происходит, вы можете ознакомиться с Tokio Tutorial:
// https://tokio.rs/tokio/tutorial
pub async fn multiple_pages(urls: &[&str]) -> Result> {
    // Конкурентно вызываем page() для каждой входящей ссылки
    let handles: Vec<_> = urls
        .iter()
        // Передача данных в асинхронные треды требует владения
        // Это может быть решено использованием крейта async-scoped, но это выходит за рамки статьи
        .map(|url| url.to_string())
        .map(|url| tokio::spawn(async move { page(&url).await }))
        .collect();

    let mut pages = Vec::with_capacity(handles.len());
    // Получаем результаты в вектор
    for handle in handles {
        pages.push(handle.await??);
    }

    Ok(pages)
}

from typing import List, Optional

import model

# В данном модуле будет находиться код, специфичный для вашего приложения


def main_page_to_genre_top_100_urls(_page: str) -> Optional[List[str]]:
    raise NotImplementedError


def genre_top_100_pages_to_reports(_pages: List[str]) -> Optional[List[model.Report]]:
    raise NotImplementedError

use crate::model;
use anyhow::Result;

// В данном модуле будет находиться код, специфичный для вашего приложения

// Для подобных конверсий в Rust следует реализовывать трейты From, TryFrom, FromStr,
// Но это бы сильно усложнило пример в данном случае
pub fn main_page_to_genre_top_100_urls(_page: &str) -> Result> {
    unimplemented!()
}

// Подробнее про тип аргумента _pages можно почитать здесь:
// https://stackoverflow.com/a/41180422/12510636
pub fn genre_top_100_pages_to_reports(_pages: &[impl AsRef]) -> Result> {
    unimplemented!()
}

Если вам всё же интересна тема HTML-парсинга, советую изучить эти библиотеки:

Для работы с подобными инструментами вам потребуются знания CSS-селекторов. Хороший материал по этой теме на русском языке доступен здесь.

Простыми словами, в CSS-файлах селекторы используются для стилизации документа, а в парсинге — для выборки данных из HTML-разметки. Например, если нужные вам данные хранятся в первом элементе с тегом

soup.select_one("div.mycontent").text

Загрузка

В предыдущих этапах мы извлекли все необходимые нам данные и преобразовали их к той форме, в которой они могут быть переданы в шаблонизатор — библиотеку, которая будет периодически генерировать наш не совсем статический веб-сайт. Кто-то может возразить, сказав, что генерация HTML-страниц также относится к этапу преобразования данных, и будет прав. Но мне удобнее ограничивать «transform» собственной программной логикой. Своеобразный mindset shift: всё, что ушло в шаблонизатор, уже относится к «load». Да и, как по мне, структура приложения при таком разграничении становится более естественной.

Создадим наш первый и единственный шаблон index.html в новой папке templates. Удобство здесь состоит в том, что мы можем переиспользовать одни и те же шаблоны в разных языках программирования. Наш index.html будет понятен как и Jinja на Python, так и Tera на Rust. Также помимо разметки применим здесь один из classless CSS-фреймворков, чтобы наша страничка выглядела хоть немного приятно.

Шаблон — templates/index.html

    
    
    


{% for report in reports -%}

    
Аналитика {{ report.genre }} Top 100 Tracks :: Beatport
    
        {% for pair in report.bpm_chart -%}
        
        {% endfor %}
    

        

            
Скорость (BPM)
        
        

            
Позиция
            
Значение
            
Количество композиций
        

            
{{ loop.index }}
            
{{ pair[1] }}
            
{{ pair[0] }}
        
    
        {% for pair in report.key_chart -%}
        
        {% endfor %}
    

        

            
Тональность (Key)
        
        

            
Позиция
            
Значение
            
Количество композиций
        

            
{{ loop.index }}
            
{{ pair[1] }}
            
{{ pair[0] }}
        

{% endfor %}

Теперь взглянем на код, который будет передавать нашу финальную структуру данных в шаблонизатор, а также сохранять результат в файл.

Python: генерация веб-страницы — load.py

import os
from typing import List

from jinja2 import Environment, FileSystemLoader

import model

TEMPLATE_PATH = "templates"
INDEX_NAME = "index.html"
BUILD_PATH = "build"


# Чтобы понять, что здесь происходит, вы можете ознакомиться с Jinja Documentation:
# https://jinja.palletsprojects.com/
def build(reports: List[model.Report]):
    # Создаём папку для билда
    os.makedirs(BUILD_PATH, exist_ok=True)

    # Инициализируем движок шаблонов Jinja
    # Этот этап рекомендуется выполнять только один раз
    jinja = Environment(loader=FileSystemLoader(TEMPLATE_PATH))

    # Рендерим содержимое
    content = jinja.get_template(INDEX_NAME).render(reports=reports)

    # Открываем файл на чтение
    with open(os.path.join(BUILD_PATH, INDEX_NAME), "w", encoding="utf-8") as f:
        # Заполняем файл содержимым
        f.write(content)

Rust: генерация веб-страницы — src/load.rs

use crate::model;
use anyhow::Result;
use std::path::Path;
use tera::{Context, Tera};
use tokio::fs;
use tokio::io::AsyncWriteExt;

const TEMPLATE_PATH: &str = "templates/**/*.html";
const INDEX_NAME: &str = "index.html";
const BUILD_PATH: &str = "build";

// Чтобы понять, что здесь происходит, вы можете ознакомиться с Tera Documentation:
// https://tera.netlify.app/docs/
pub async fn build(reports: model::ReportVec) -> Result<()> {
    // Создаём папку для билда
    fs::create_dir_all(BUILD_PATH).await?;

    // Инициализируем движок шаблонов Tera
    // Этот этап рекомендуется выполнять только один раз
    let tera = match Tera::new(TEMPLATE_PATH) {
        Ok(t) => t,
        Err(e) => {
            println!("Parsing error(s): {e}");
            ::std::process::exit(1);
        }
    };

    // Рендерим содержимое
    let content = tera.render(INDEX_NAME, &Context::from_serialize(reports)?)?;

    // Определяем путь конечного файла
    let index_path = Path::new(BUILD_PATH).join(INDEX_NAME);

    // Открываем файл на чтение
    let mut file = fs::File::create(index_path).await?;

    // Заполняем файл содержимым
    file.write_all(content.as_bytes()).await?;

    Ok(())
}

Результатом выполнения скрипта станет папка build с содержимым вашего веб-сайта. В моём кейсе это будет единственный index.html, но ничто не мешает добавлять контент по вашему разумению. Вы вправе генерировать столько HTML-страниц, сколько вам необходимо, а также добавлять соответствующую статику: CSS, JavaScript и тому подобное. И, конечно же, если вы используете Node.js, вы без проблем можете собирать ваш ресурс, используя npm run build.

Шаблон, заполненный данными

Всё, что остаётся, это «доставить» нашу сборку до пользователей, воспользовавшись средствами GitHub.

Actions

Где же будет выполняться наш код? Где будет генерироваться наш build? В «раннере» GitHub Actions — виртуальной машине, которая будет существовать только на момент сборки веб-сайта. Мы будем использовать «раннер» с Ubuntu Linux, хотя при желании можно использовать и Windows, и macOS.

Как я уже указал выше, вам следует учитывать ограничения GitHub Actions, если вы используете их в приватных репозиториях. Но есть еще один момент, про который стоит упомянуть — минуты ОС имеют разную стоимость:

• Linux — бесплатно 2000 минут (33 часа 20 минут) в месяц

• Windows — множитель x2 — бесплатно 1000 минут (16 часов 40 минут) в месяц

• macOS — множитель х10 (!!!) — бесплатно 200 минут (3 часа 20 минут) в месяц

Но, повторюсь, эти ограничения не относятся ко времени доступности вашего веб-сайта, он будет доступен постоянно. Данные значения влияют только на время, доступное вашему коду на генерацию содержимого. И, опять же, только в приватных репозиториях.

Теперь давайте определимся, какие шаги должен регулярно выполнять наш «раннер»:

1. Загрузить код репозитория в окружение

2. Установить средства языка для компиляции / интерпретации кода

3. Подтянуть необходимые библиотеки и зависимости

4. (По желанию) проверить код линтером и прогнать тесты

5. Исполнить код нашего приложения, получив на выходе папку build с актуальным содержимым

6. Запушить билд в отдельную ветку текущего или стороннего репозитория

Эти действия должны быть декларативно описаны в YAML-файле, который будет помещён в каталог .github/workflows текущего репозитория. Такие файлы называются рабочими процессами (workflows), и при желании их может быть несколько. Внутри файла рабочего процесса необходимо указать, какие события (events) будут запускать его. Типов событий довольно много, но чаще всего используется обычный git push. Мы также добавим событие schedule, позволяющее запускать процессы по расписанию.

Внутри каждого рабочего процесса вы также можете задавать произвольное количество заданий (jobs), каждое из которых обычно выполняется параллельно на отдельных виртуальных машинах. В нашем примере будет один файл рабочего процесса с одним заданием.

Задания, в свою очередь, состоят из шагов (steps). Шагами могут быть классические команды терминала, а также действия (actions), то есть часто используемые операции, которые были размещены на GitHub Marketplace. Проще всего думать о действиях как об удобных внешних функциях, которые мы можем вызывать из нашего YAML-кода.

Рабочие процессы для Python и Rust будут отличаться, но некоторые шаги будут оставаться общими:

• Загрузка кода репозитория (1-й пункт) будет проводиться через официальный actions/checkout

• А деплой билда в отдельную ветку репо (6-й пункт) — через peaceiris/actions-gh-pages

Сначала разрешим нашему будущему рабочему процессу вносить изменения в наш репозиторий. Для этого зайдём на GitHub в Settings > Actions > General > Workflow Permissions и изменим значение на Read and write permissions.

Далее создадим папку .github/workflows, а в ней файл main.yml. Так как в моём кейсе не требуется частое обновление данных, я укажу, чтобы веб-сайт обновлялся один раз в сутки.

Python: рабочий процесс — .github/workflows/main.yml

# Название рабочего процесса
name: Main Workflow (Python)

# События, запускающие процесс
on:
  # Git push в ветку main
  push:
    branches:
      - main

  # По расписанию: каждый день в 0:00 UTC
  # https://crontab.guru/every-day
  schedule:
    - cron: '0 0 * * *'

# Задания
jobs:
  # Название задания
  Main-Job-Python:
    # Запускать на последней версии Ubuntu
    runs-on: ubuntu-latest

    # Шаги
    steps:
      # Загрузить код репозитория в окружение
      - name: Checkout repository
        uses: actions/checkout@v3

      # Установить Python 3.10
      - name: Install Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'

      # Установить зависимости
      - name: Install Dependencies
        run: pip install -r requirements.txt

      # Запустить нашу программу на Python
      # Этот шаг генерирует папку ./build
      - name: Run
        run: python main.py

      # Разместить содержимое ./build в корень ветки gh-pages текущего репо
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          # Передача токена рабочего прицесса во внешнее действие
          # Не требует отдельной настройки секретов, токен передаётся автоматически
          github_token: ${{ secrets.GITHUB_TOKEN }}
          # Выбор папки билда
          publish_dir: ./build

Rust: рабочий процесс — .github/workflows/main.yml

# Название рабочего процесса
name: Main Workflow (Rust)

# События, запускающие процесс
on:
  # Git push в ветку main
  push:
    branches:
      - main

  # По расписанию: каждый день в 0:00 UTC
  # https://crontab.guru/every-day
  schedule:
    - cron: '0 0 * * *'

# Задания
jobs:
  # Название задания
  Main-Job-Rust:
    # Запускать на последней версии Ubuntu
    runs-on: ubuntu-latest

    # Шаги
    steps:
      # Загрузить код репозитория в окружение
      - name: Checkout repository
        uses: actions/checkout@v3

      # Установить последний стабильный Rust
      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@stable

      # Использовать кэш между рабочими процессами при компилировании Rust-библиотек
      # ЗНАЧИТЕЛЬНО ускоряет выполнение рабочего процесса в случае с Rust
      - name: Rust Cache
        uses: Swatinem/rust-cache@v2

      # Запустить нашу программу на Rust
      # Этот шаг генерирует папку ./build
      - name: Run
        run: cargo run --release

      # Разместить содержимое ./build в корень ветки gh-pages текущего репо
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          # Передача токена рабочего прицесса во внешнее действие
          # Не требует отдельной настройки секретов, токен передаётся автоматически
          github_token: ${{ secrets.GITHUB_TOKEN }}
          # Выбор папки билда
          publish_dir: ./build

Сохраняем main.yml и пробуем сделать коммит.

Если всё было сделано верно, то на GitHub напротив нашего коммита появится оранжевый кружок, который даст сигнал, что рабочий процесс был запущен. Через некоторое время на его месте должна появиться зелёная галочка. Если во время процесса возникнут ошибки, то их можно будет изучить в разделе Actions.

Также обратим внимание на новое предупреждение. Оно связано с тем, что в репозитории была создана ветка gh-pages.

Жмём Protect this branch, а затем Require a pull request before merging и Create. При желании вы можете изучить правила защиты ветвей здесь. Остаётся сделать последний шаг, после которого ваш веб-сайт станет доступен для всех.

Pages

Взглянув на список веток репозитория, вы можете убедиться, что рабочий процесс самостоятельно создал ветку gh-pages и поместил туда сгенерированное содержимое. Начиная с этого момента каждый коммит в main будет обновлять gh-pages. Также ранее мы настроили событие schedule, которое будет ежедневно обновлять gh-pages независимо от коммитов.

Снизу появилась новая ветка

Внесём последнее изменение, которое разместит содержимое ветки gh-pages на бесплатном хостинге GitHub Pages. Проследуем в Settings > Pages. Изменим Branch на gh-pages и нажмём Save.

Подождём пару минут и проверим, что наша страничка стала доступна для всех. Попробуем пройти по этой ссылке:

https://ваш_логин.github.io/имя_репозитория/

Обратите внимание, что на конце домена стоит .io, а не .com. В моём случае (после внушительной доработки и полировки решения кейса) ссылка получилась такой:

https://sergree.github.io/whatbpm/

Итог

Используя этот метод, мы получили веб-сервис, способный обновлять представленную на нём информацию с допустимым заданным интервалом. Да, эту страницу нельзя назвать динамической, но, как по мне, совершенно статической она также не является. Содержимое отображает релевантную информацию, исполняя бизнес-требования. В вышеуказанном кейсе это означает, что EDM продюсеры могут использовать аналитику с этой страницы для обдуманного выбора скорости (BPM) и тональности (Key) своих будущих композиций. Учитывая характер данных, мы смогли немного пренебречь актуальностью. Для музыкантов не так важно основывается ли эта аналитика на данных в реальном времени, или присутствует задержка не более суток. При необходимости мы могли бы уменьшить эту задержку до нескольких минут.

Если потребуется, к страничке на GitHub Pages можно привязать свой домен. Подробная инструкция на эту тему находится здесь. Также, если вы не хотите публиковать код генерации сайта, вы можете воспользоваться тем, что peaceiris/actions-gh-pages позволяет размещать сгенерированное содержимое в отдельном репозитории. В таком случае у вас могло бы быть два репозитория: приватный для генерации контента на GitHub Actions, публичный для его отображения на GitHub Pages. Но в случае с приватным репо у вас есть только 33 часа бесплатного времени GitHub Actions в месяц.

Вариант с приватным репо мог бы выглядеть так

Решение кейса, описанного в статье, представляет собой stateless-приложение. Но что делать, если у подобного веб-сайта должно быть собственное состояние? Так как в данном случае не требуется транзакционность, можно было бы обойтись хранением стейта в отдельном файле ветки gh-pages. Это мог бы быть простой CSV или JSON. Либо вы могли бы воспользоваться бесплатным DBaaS из этого списка.

Способ #1 — хранение состояния в Git-репозиторииСпособ #2 — хранение состояния в DBaaS

Всё это, конечно, выглядит не так просто, как хотелось бы. Что делать, если всего лишь хочется перенести свой WordPress-блог на бесплатный GitHub Pages? В данном случае я бы посмотрел в сторону Jekyll и Hugo. Но здесь также стоит учитывать ограничение размера сайта на GitHub Pages в 1 Гбайт.

Альтернативный способ решения задачи — на клиенте