Como criar um plugin?

O sistema de plugins usado pelo sociopyta é o pluggy e existem dois tipos de plugins para o pluggy:

Publisher: Plugin responsável pela postagem de conteúdo em redes sociais.
Syncer: Plugin utilizado para obter dados de fontes externas para sincronização.

O pacote

O pacote pode ser feito da maneira que você achar melhor flat, scr, usar a ferramenta de empacotamento que achar melhor.

📁 socialXY
├── 📁 src
│   └── 📄 socialXY.py
└── 📄 pyproject.toml

A única configuração necessária para o descobrimento do plugin pelo sociopyta é o entry-points. Caso queira usar as bibliotecas previamente instaladas pelo sociopyta é interessante adicionar ele como dependência do projeto:

pyproject.toml

[project]
# ...
dependencies = [
  "pluggy",
  "sociopyta @ git+https://codeberg.org/dunossauro/sociopyta.git"
]

[project.entry-points.sociopyta] #(1)!
socialXY = "sociopyta_socialXY_plugin"

O namespace sociopyta é o que fará o plugin ser reconhecido pelo sociopyta.

Configuração

A ideia da configuração é obter os dados necessários para que o plugin possa ser usado.

Os plugins nativos usam InquirerPy para fazer isso com uma interface mais agradável, como o sociopyta já instala ele, você pode usar, se quiser.

Vamos imaginar que sua rede se chame socialXY:

socialXY_plugin.py

import sociopyta

@sociopyta.hookimpl
def config(config_file: Path) -> None:
    data = {
        'access_token': inquirer.text(
            'access_token :',
            is_password=True,
        ).execute(),
        'instance_url': inquirer.text(
            'instance_url :',
            validate=lambda i: i.startswith('https://'),
            completer={'https://': None}
        ).execute(),
    }

A ideia no final é que você escreva tabela com a configuração no arquivo sociopyta.toml. Algo como:

[socialXY]
access_token = 'seu_token'
instance_url = 'https://instancia.com'

O sociopyta tem uma função no namespace que pode te ajudar com isso: sociopyta.add_table_to_toml(). Caso você queira não se preocupar com isso.

A localização do arquivo é data pelo platformdirs.

O caminho da configuração pode ser obtido com:

from pathlib import Path
from platformdirs import user_config_dir


config_dir = Path(user_config_dir('sociopyta', 'sociopyta'))
config_file = Path(config_dir) / 'sociopyta.toml'

Caso seja necessário usar cache, logs, estados, dê preferência pelo namespace sociopyta/sociopyta disponíveis no platformdirs.

Publisher

Os plugins de publish precisam implementar o hook config.

Os plugins são baseados em módulos e funções. Para publicação todo o código deve ser implementado em uma função chamada post.

Vamos imaginar que sua rede se chame socialXY:

socialXY_plugin.py

import sociopyta

@sociopyta.hookimpl
def post(text, images, config) -> tuple[str, str] | None:
    try:
        access_token = config.socialXY.access_token
        handle = config.socialXY.handle
    except:
        return None
    ...

    return 'social_name', 'post_url'

O resultado sempre deve ser uma tupla de duas str. Onde a primeira deverá ser o nome da rede social e a segunda o link da postagem.

Notas para implementação:

Se seu plugin for para uma rede de imagens, como pixelfed, não se esqueça de implementar um skip, caso não existam imagens no post.
Faça um skip também se sua rede não estiver sido configurada. Algo como tentar obter a configuração, caso ela não exista, skip.
Evite implementações complexas nessa função. Uma boa solução pode ser implementar tudo fora e somente a postagem no seu hook.
Caso você precise fazer requisições HTTP, o HTTPX já está instalado como dependência do pacote base do sociopyta.

Syncer

Os plugins de sync precisam implementar o hook config.

TODO