Criação do Client.occurrences()

[FelipeSBarros]

@cuducos comecei a criação do client.occurrences().

Na documentação são apresentados alguns exemplos de uso. eu fiz alguns testes e algumas coisas me chamara a atenção. Já me comuniquei com o Davi, desenvolvedor deles, para confirmar alguns pontos, como:

• Só consigo acessar dados de uma cidade colocando o id dela E o id do estado. Ao informar apenas id da cidade, nada éretornado.
• [logo,] Só são retornados dados se ao menos o id do estado for informado;

Em se confirmando que para acessar dados de ocorrência temos que informar o id do estado, seria o caso de levantar um erro, né?

Alguns pontos para trabalhar:

• O parâmetro typeOccurrence=withVictim ainda não foi implementado pois não seri quais seriam os valores possíveis.
  Adicionar ao Occurrences o parâmetros typeOccurrence #39
• Podem ser solicitadas mais de uma cidade;
  Occurrences deve poder retornar dados de mais de uma cidade #38
• Trabalhar com a paginação;
• criar testes específicos para cada parametro de Ocurrence
  Criar testes para parâmetros de Occurrences #40

[cuducos]

Em se confirmando que para acessar dados de ocorrência temos que informar o id do estado, seria o caso de levantar um erro, né?

Creio que não. Ou pelo menos, não é dever nosso (de quem escreve o pacote) levantar esse erro. O que eu quero dizer é que isso tem que ser requisito da API. Se ID do estado é obrigatório, não podemos ter occurences(state_id=None) mas occurences(state_id).

Isso levanta um erro. Mas o que fazemos (nós) não é levantar o erro, é refletir no design da API a situação : )

[cuducos]

Fiz uma requisição para states e peguei o id de cada UF. Depois peguei o pageMeta para as ocorrências de cada um deles:

{"page": 1, "take": 50, "itemCount": 39795, "pageCount": 796, "hasPreviousPage": false, "hasNextPage": true}
{"page": 1, "take": 50, "itemCount": 8866, "pageCount": 178, "hasPreviousPage": false, "hasNextPage": true}
{"page": 1, "take": 50, "itemCount": 2065, "pageCount": 42, "hasPreviousPage": false, "hasNextPage": true}

Digamos que cada requisição leve 0,5 segundo. Se formos retornar todas as ocorrências para a primeira UF, isso demoraria quase 7min. Acho uma péssima experiência para quem está utilizando. Melhor descartar a ideia de retornar todas as ocorrências de uma vez.

Pensei em talvez client.occurences() ser um gerador, que vai retornando ocorrências comforme quem utiliza quiser:

for count, occurence in enumerate(client.occurences(state_id=42), 1):
    print(occurence)
    if count == 51:
        break

Como a API retorna 50 por página, esse código geraria apenas duas requisições (ao invés de 796). Isso poderia ser implementado. Quando chamamos occurences() podemos verificar sem tem ocorrências já baixadas da API e não entregues a quem utiliza a API. Se tiver, devolvemos uma delas, sem necessidade de nova requisição HTTP. Quando esse buffer estiver vazio, vemos se tem próxima página. Se tiver, fazemos a requisção, devolvemos a primeira ocorrência e colocamos as restantes no buffer.

sequenceDiagram
    autonumber
    actor User

    User->>Occurences: next()

    rect rgb(239,224,209)

        Occurences->>Buffer: Checks if buffer is empty

        rect rgb(239,239,239)
            Note over Buffer, API Fogo Cruzado: Only when buffer is empty

            Buffer->>API Fogo Cruzado: HTTP request
            API Fogo Cruzado->>Buffer: HTTP response
        end

        Buffer->>Occurences: occurence
        Note over Occurences, API Fogo Cruzado: Generator
    end

    Occurences->>User: yield

ATUALIZAÇÃO Esqueci de mencionar, que o buffer pode ser só uma fila FIFO nativa:

In [1]: from queue import Queue

In [2]: q = Queue()

In [3]: q.put(1)

In [4]: q.put(2)

In [5]: q.put(3)

In [6]: q.get()
Out[6]: 1

In [7]: q.get()
Out[7]: 2

[cuducos]

🚀

[cuducos]

Algum motivo para o PR continuar como draft? Se não tiver, pode dar o merge na minha opnião : )

[FelipeSBarros]

Algum motivo para o PR continuar como draft? Se não tiver, pode dar o merge na minha opnião : )

uma revisão sua ;)
Entendo que posso dar o merge, então!