congrega_plenum 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/README.md CHANGED
@@ -1,19 +1,23 @@
1
+ <picture>
2
+ <source media="(prefers-color-scheme: dark)" srcset="assets/branding/diafania-claritas-logo-inverse.svg">
3
+ <source media="(prefers-color-scheme: light)" srcset="assets/branding/diafania-claritas-logo.svg">
4
+ <img alt="Diafania Claritas: o Congresso Nacional observado por um olho" src="assets/branding/diafania-claritas-logo.svg" width="560">
5
+ </picture>
6
+
1
7
  # CongregaPlenum
2
8
 
3
- [![CI](https://github.com/zarbielli/CongregaPlenum/actions/workflows/ci.yml/badge.svg)](https://github.com/zarbielli/CongregaPlenum/actions/workflows/ci.yml)
4
- [![Coverage](https://img.shields.io/endpoint?url=https%3A%2F%2Fzarbielli.github.io%2FCongregaPlenum%2Fcoverage.json)](https://github.com/zarbielli/CongregaPlenum/actions/workflows/ci.yml)
5
- [![Documentation](https://github.com/zarbielli/CongregaPlenum/actions/workflows/docs.yml/badge.svg)](https://zarbielli.github.io/CongregaPlenum/)
6
- [![License: GPL-2.0](https://img.shields.io/badge/license-GPL--2.0-blue.svg)](LICENSE)
9
+ [![CI](https://github.com/Diafania-Claritas/CongregaPlenum/actions/workflows/ci.yml/badge.svg)](https://github.com/Diafania-Claritas/CongregaPlenum/actions/workflows/ci.yml)
10
+ [![Coverage](https://img.shields.io/endpoint?url=https%3A%2F%2Fdiafania-claritas.github.io%2FCongregaPlenum%2Fcoverage.json)](https://github.com/Diafania-Claritas/CongregaPlenum/actions/workflows/ci.yml)
11
+ [![Documentation](https://github.com/Diafania-Claritas/CongregaPlenum/actions/workflows/docs.yml/badge.svg)](https://diafania-claritas.github.io/CongregaPlenum/)
12
+ [![Gem Version](https://img.shields.io/gem/v/congrega_plenum.svg)](https://rubygems.org/gems/congrega_plenum)
13
+ [![License: AGPL-3.0-or-later](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](LICENSE)
7
14
 
8
15
  Cliente Ruby para a [API de Dados Abertos da Câmara dos Deputados](https://dadosabertos.camara.leg.br/),
9
16
  com paginação, retries, logging e serviços para deputados, partidos e
10
- legislaturas. O projeto inclui assinaturas RBS e uma API orientada a
17
+ legislaturas e votações. O projeto inclui assinaturas RBS e uma API orientada a
11
18
  sincronizações e aplicações de dados cívicos.
12
19
 
13
- > O projeto está em desenvolvimento inicial e ainda não possui uma versão
14
- > publicada no RubyGems.
15
-
16
- - [Documentação da API](https://zarbielli.github.io/CongregaPlenum/)
20
+ - [Documentação da API](https://diafania-claritas.github.io/CongregaPlenum/)
17
21
  - [Como contribuir](CONTRIBUTING.md)
18
22
  - [Changelog](CHANGELOG.md)
19
23
  - [Política de segurança](SECURITY.md)
@@ -26,11 +30,10 @@ sincronizações e aplicações de dados cívicos.
26
30
 
27
31
  ## Instalação
28
32
 
29
- Enquanto não houver uma versão publicada no RubyGems, adicione o repositório ao
30
- seu `Gemfile`:
33
+ Adicione a gem ao seu `Gemfile`:
31
34
 
32
35
  ```ruby
33
- gem 'congrega_plenum', github: 'zarbielli/CongregaPlenum'
36
+ gem 'congrega_plenum', '~> 0.3.0'
34
37
  ```
35
38
 
36
39
  Depois execute:
@@ -39,6 +42,15 @@ Depois execute:
39
42
  bundle install
40
43
  ```
41
44
 
45
+ Ou instale diretamente pelo RubyGems:
46
+
47
+ ```bash
48
+ gem install congrega_plenum -v '~> 0.3.0'
49
+ ```
50
+
51
+ Consulte a [página da gem no RubyGems](https://rubygems.org/gems/congrega_plenum)
52
+ para conferir as versões publicadas.
53
+
42
54
  ## Configuração
43
55
 
44
56
  ```ruby
@@ -81,6 +93,11 @@ Outros fluxos disponíveis:
81
93
  - `CongregaPlenum::VotingsService.fetch_votes(voting_id)`
82
94
  - `CongregaPlenum::VotingsService.fetch_orientations(voting_id)`
83
95
 
96
+ Para uma sincronização retomável de catálogos, use `fetch_page` em
97
+ `CongressmenService`, `PartiesService` ou `LegislaturesService`. O resultado
98
+ fornece `records` e `next_page`. `next_page` é `nil` no fim da lista. Respostas
99
+ sem uma lista explícita ou com continuação inválida levantam `APIError`.
100
+
84
101
  Uma votação representa uma decisão legislativa individual já concluída. Uma
85
102
  proposição pode ser afetada por várias votações de pareceres, emendas,
86
103
  requerimentos e destaques relacionados. Por isso, detalhes, votos individuais e
@@ -104,7 +121,7 @@ ao mesmo ano. Votações simbólicas normalmente não possuem votos individuais,
104
121
  uma lista de votos vazia não identifica quais deputados estavam ausentes.
105
122
 
106
123
  Para controle de baixo nível, use `CongregaPlenum::Client`. Consulte a
107
- [documentação YARD](https://zarbielli.github.io/CongregaPlenum/) para os contratos
124
+ [documentação YARD](https://diafania-claritas.github.io/CongregaPlenum/) para os contratos
108
125
  completos.
109
126
 
110
127
  ## Desenvolvimento
@@ -131,7 +148,9 @@ públicas; siga a [política de segurança](SECURITY.md).
131
148
 
132
149
  ## Licença
133
150
 
134
- Distribuído sob a [GNU General Public License v2.0](LICENSE).
151
+ Distribuído sob a [GNU Affero General Public License v3.0 ou posterior](LICENSE).
152
+ Aplicações que incorporam a gem e são distribuídas ou disponibilizadas para
153
+ uso por rede devem observar as obrigações de código-fonte da AGPL.
135
154
 
136
155
  CongregaPlenum é um projeto independente e não é afiliado à Câmara dos
137
156
  Deputados.
@@ -0,0 +1,54 @@
1
+ # frozen_string_literal: true
2
+
3
+ module CongregaPlenum
4
+ # One validated catalogue page. Repeated identities remain in source order.
5
+ CatalogPage = Data.define(:records, :next_page) do
6
+ # Validates the API envelope and extracts sequential pagination metadata.
7
+ def self.parse(response, page:)
8
+ records = records_from(response)
9
+ links = links_from(response)
10
+ next_page = continuation(links, page)
11
+ raise APIError, 'empty catalogue page cannot continue' if next_page && records.empty?
12
+
13
+ new(records: records.freeze, next_page: next_page)
14
+ end
15
+
16
+ def self.records_from(response)
17
+ records = response['dados']
18
+ return records if records.is_a?(Array) && records.all?(Hash)
19
+
20
+ raise APIError, 'catalogue page requires an explicit list of objects in dados'
21
+ end
22
+ private_class_method :records_from
23
+
24
+ def self.links_from(response)
25
+ links = response['links']
26
+ return links if links.is_a?(Array) && links.all? { |link| link.is_a?(Hash) && link['rel'].is_a?(String) }
27
+
28
+ raise APIError, 'catalogue page requires pagination links'
29
+ end
30
+ private_class_method :links_from
31
+
32
+ def self.continuation(links, page)
33
+ next_links = links.select { |link| link['rel'] == 'next' }
34
+ return if next_links.empty?
35
+
36
+ unless next_links.one? && page_parameter(next_links.first['href']) == [(page + 1).to_s]
37
+ raise APIError, 'invalid catalogue page continuation'
38
+ end
39
+
40
+ page + 1
41
+ end
42
+ private_class_method :continuation
43
+
44
+ def self.page_parameter(href)
45
+ return [] unless href.is_a?(String)
46
+
47
+ query = URI.parse(href).query.to_s
48
+ URI.decode_www_form(query).filter_map { |name, value| value if name == 'pagina' }
49
+ rescue URI::InvalidURIError, ArgumentError
50
+ raise APIError, 'invalid catalogue page continuation'
51
+ end
52
+ private_class_method :page_parameter
53
+ end
54
+ end
data/lib/client.rb CHANGED
@@ -44,6 +44,13 @@ module CongregaPlenum
44
44
  results
45
45
  end
46
46
 
47
+ # Retrieves and validates one page without discarding continuation metadata.
48
+ def get_catalog_page(endpoint, page:, params: {})
49
+ raise ArgumentError, 'page must be a positive integer' unless page.is_a?(Integer) && page.positive?
50
+
51
+ CatalogPage.parse(get(endpoint, params.merge(pagina: page)), page: page)
52
+ end
53
+
47
54
  private
48
55
 
49
56
  def each_response_page(endpoint, params)
@@ -76,6 +76,7 @@ end
76
76
  require_relative 'adapters/http_adapter'
77
77
  require_relative 'adapters/retry_policy'
78
78
  require_relative 'adapters/response_handler'
79
+ require_relative 'catalog_page'
79
80
  require_relative 'client'
80
81
  require_relative 'modules/congressmen_service'
81
82
  require_relative 'modules/parties_service'
@@ -84,6 +84,12 @@ module CongregaPlenum
84
84
  response['dados'] || []
85
85
  end
86
86
 
87
+ # Returns one validated catalogue page with its next page, if published.
88
+ def fetch_page(page: 1, items_per_page: ITEMS_PER_PAGE, legislature_id: nil)
89
+ params = { idLegislatura: legislature_id, itens: items_per_page, ordem: 'ASC', ordenarPor: 'id' }.compact
90
+ client.get_catalog_page('deputados', page: page, params: params)
91
+ end
92
+
87
93
  private
88
94
 
89
95
  def extract_detail(response, resource)
@@ -86,6 +86,12 @@ module CongregaPlenum
86
86
  deputies
87
87
  end
88
88
 
89
+ # Returns one validated catalogue page with its next page, if published.
90
+ def fetch_page(page: 1, items_per_page: PAGE_SIZE)
91
+ params = { itens: items_per_page }.compact
92
+ client.get_catalog_page('legislaturas', page: page, params: params)
93
+ end
94
+
89
95
  private
90
96
 
91
97
  def extract_detail(response, resource)
@@ -76,6 +76,12 @@ module CongregaPlenum
76
76
  response['dados'] || []
77
77
  end
78
78
 
79
+ # Returns one validated catalogue page with its next page, if published.
80
+ def fetch_page(page: 1, items_per_page: ITEMS_PER_PAGE)
81
+ params = { itens: items_per_page, ordem: 'ASC', ordenarPor: 'id' }.compact
82
+ client.get_catalog_page('partidos', page: page, params: params)
83
+ end
84
+
79
85
  private
80
86
 
81
87
  def extract_detail(response, resource)
data/lib/version.rb CHANGED
@@ -2,5 +2,5 @@
2
2
 
3
3
  module CongregaPlenum
4
4
  # Current gem version.
5
- VERSION = '0.1.0'
5
+ VERSION = '0.3.0'
6
6
  end
@@ -67,6 +67,13 @@ module CongregaPlenum
67
67
  def parse_json_response: (::Net::HTTPResponse, String) -> payload_hash
68
68
  end
69
69
 
70
+ class CatalogPage
71
+ attr_reader records: payload_list
72
+ attr_reader next_page: Integer?
73
+ def self.new: (records: payload_list, next_page: Integer?) -> instance
74
+ def self.parse: (payload_hash, page: Integer) -> instance
75
+ end
76
+
70
77
  class Client
71
78
  include ::Singleton
72
79
 
@@ -77,6 +84,7 @@ module CongregaPlenum
77
84
 
78
85
  def initialize: () -> void
79
86
  def get: (String, ?params_hash) -> payload_hash
87
+ def get_catalog_page: (String, page: Integer, ?params: params_hash) -> CatalogPage
80
88
  def get_paginated: (String, ?params_hash) -> payload_list
81
89
  def each_response_page: (String, params_hash) { (payload_list) -> void } -> void
82
90
  def request_page: (String, params_hash, Integer) -> payload_hash
@@ -97,6 +105,7 @@ module CongregaPlenum
97
105
  def self.api_get_paginated: (String, ?params_hash) -> payload_list
98
106
  def self.fetch_all: () -> payload_list
99
107
  def self.fetch_all_by_legislature: (Integer) -> payload_list
108
+ def self.fetch_page: (?page: Integer, ?items_per_page: Integer, ?legislature_id: Integer?) -> CatalogPage
100
109
  def self.fetch_by_id: (Integer) -> detail_payload
101
110
  def self.fetch_list: (?page: Integer, ?items_per_page: Integer, ?legislature_id: Integer?) -> payload_list
102
111
  def self.fetch_deputies_collection: (context: String, params: params_hash) -> payload_list
@@ -118,6 +127,7 @@ module CongregaPlenum
118
127
  def self.api_get: (String, ?params_hash) -> payload_hash
119
128
  def self.api_get_paginated: (String, ?params_hash) -> payload_list
120
129
  def self.fetch_all: () -> payload_list
130
+ def self.fetch_page: (?page: Integer, ?items_per_page: Integer) -> CatalogPage
121
131
  def self.fetch_by_id: (Integer) -> detail_payload
122
132
  def self.fetch_list: (?page: Integer, ?items_per_page: Integer) -> payload_list
123
133
  def self.extract_detail: (payload_hash, String) -> detail_payload
@@ -138,6 +148,7 @@ module CongregaPlenum
138
148
  def self.api_get: (String, ?params_hash) -> payload_hash
139
149
  def self.api_get_paginated: (String, ?params_hash) -> payload_list
140
150
  def self.fetch_all: () -> payload_list
151
+ def self.fetch_page: (?page: Integer, ?items_per_page: Integer) -> CatalogPage
141
152
  def self.fetch_by_id: (Integer) -> detail_payload
142
153
  def self.fetch_mesa: (Integer) -> payload_list
143
154
  def self.fetch_deputies: (Integer) -> payload_list
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: congrega_plenum
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.0
4
+ version: 0.3.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - zarbielli
@@ -23,6 +23,7 @@ files:
23
23
  - lib/adapters/http_adapter.rb
24
24
  - lib/adapters/response_handler.rb
25
25
  - lib/adapters/retry_policy.rb
26
+ - lib/catalog_page.rb
26
27
  - lib/client.rb
27
28
  - lib/congrega_plenum.rb
28
29
  - lib/modules/congressmen_service.rb
@@ -31,14 +32,14 @@ files:
31
32
  - lib/modules/votings_service.rb
32
33
  - lib/version.rb
33
34
  - sig/congrega_plenum.rbs
34
- homepage: https://github.com/zarbielli/CongregaPlenum
35
+ homepage: https://github.com/Diafania-Claritas/CongregaPlenum
35
36
  licenses:
36
- - GPL-2.0-only
37
+ - AGPL-3.0-or-later
37
38
  metadata:
38
39
  allowed_push_host: https://rubygems.org
39
- homepage_uri: https://github.com/zarbielli/CongregaPlenum
40
- source_code_uri: https://github.com/zarbielli/CongregaPlenum
41
- changelog_uri: https://github.com/zarbielli/CongregaPlenum/blob/main/CHANGELOG.md
40
+ homepage_uri: https://github.com/Diafania-Claritas/CongregaPlenum
41
+ source_code_uri: https://github.com/Diafania-Claritas/CongregaPlenum
42
+ changelog_uri: https://github.com/Diafania-Claritas/CongregaPlenum/blob/main/CHANGELOG.md
42
43
  rubygems_mfa_required: 'true'
43
44
  rdoc_options: []
44
45
  require_paths: