Package: python-rebase
Python ReBase [0.3.3]Este projeto é uma API escrita em Python para comunicação com o ReBase, um banco de dados de sessões de reabilitação física.ÍndicePython ReBase [0.3.3]ÍndiceVisão GeralSobre o ReBaseInstalaçãoRequisitosQuick StartInicializando o ReBaseClientCriando um MovimentoCriando uma SessãoBuscando Movimentos e SessõesAtualizando e deletandoTópicos AvançadosFiltragemPaginaçãoExemplosDocumentação CompletaReBaseClientMódulosutilModelosAPIResponseMovementRegisterRotationSessionErrosContatoVisão GeralO pacote Python ReBase contém classes-modelo para Sessões e Movimentos. A classeapi_responsemodela de forma generalizada as respostas enviadas peloReBaseRS. O módulorebase_clienté responsável pelo envio de requisições ao ReBaseRS. Estão inclusas também algumas exceções personalizadas e funções utilitárias. Todos os módulos se encontram na pastasrc/python_rebase.Sobre o ReBaseO ReBase, do inglêsRehabilitation Database, é um baco de dados dedicado ao armazenamento de movimentos corporais, com foco em reabilitação neurofuncional e neuromotora. Apesar do enfoque, o ReBase é capaz de armazenar qualquer tipo de movimento corporal gravado por qualquer técnica de captura de movimentos, desde que siga o padrão definido. Para isto serve a API Python ReBase!OsMovimentosdo ReBase representam os movimentos corporais capturados e são compostos por metadados, uma lista deArticulaçõese uma lista deRegistros, que representam as rotações em X, y e z da Articulação a cada instante do Movimento. Os Movimentos podem pertencer aSessões. Cada Sessão também contem metadados e pode conter múltiplos movimentos.Todos os usuários que desejarem acessar o ReBase precisam ter um token de autenticação cadastrados no sistema. Para receber um token, o usuário deve entrar em contato com o time de desenvolvimento através dos emailsmrtrotta2010@gmail.comoudiegocolombodias@gmail.come enviar o endereço de email que deseja cadastrar.InstalaçãoO Python ReBase pode ser instalado pelo terminal através doPyPicom os comandos:pip3 install python-rebaseoupython3 -m pip install python-rebaseRequisitosEsta biblioteca depende da bibliotecarequests, utilizada para enviar requisições HTTP;O Python ReBase está disponível apenas para Python 3.10 ou superior;É necessário ter seu email e token de autenticação já cadastrados no ReBase.Quick StartPara utilizar a API, basta importar a biblioteca no começo do seu arquivo .pyInicializando o ReBaseClientfrompython_rebase.rebase_clientimportReBaseClient# Inicialize o cliente do ReBase com seu email e token previamente cadastradosrebase_client=ReBaseClient('exemplo@gmail.com','tokenExemplo')Criando um Movimentofrompython_rebase.movementimportMovement# Crie um objeto Movementmovement=Movement({'label':'MyMovement','fps':30,# Varia conforme sua aplicação'professionalId':'Prof','articulations':['1','2']})# Adicione os Registros ao Movimento# Cada registro representa um "frame" do movimento# Os registros contêm as rotações de cada articulação em um dado momento# Apesar de o Python ReBase incluir classes-modelo para os Registros e para Rotações, os métodos também aceitam dicionários e listas como parâmetrosmovement.add_register(Register({'1':Rotation(1.0,1.0,1.0),# Rotações da articulação "1"'2':[2.0,2.0,2.0]# Rotações da articulação "2"}))# Utilize o módulo rebase_client para inserir o movimentoresponse=rebase_client.insert_movement(movement)print(f'Inserted:{response}')Criando uma Sessãofrompython_rebase.sessionimportSession# Crie um objeto Sessão.# A Sessão pode ser criada vazia ou com Movimentos, sejam eles da classe Movement ou dicionários simplessession=Session({'title':'Teste de Sessão','professionalId':'Prof','patientId':'Pat','movements':[# Da mesma forma, os Movimentos podem ser criados já com RegistrosMovement({'label':'MyMovement','fps':30,'articulations':['1','2'],'registers':[Register({'1':Rotation(1.0,1.0,1.0),'2':Rotation(2.0,2.0,2.0)})]}),{'label':'MyMovement','fps':30,'articulations':['1','2'],'registers':[{'1':[1.0,1.0,1.0],'2':[2.0,2.0,2.0]}]}]})response=rebase_client.insert_session(session)Buscando Movimentos e Sessões# É possível encontrar um único Movimento ou listar váriosresponse=rebase_client.find_movement(id)print(f'Movimento:{response.movement}')# A listagem permite filtros e suporta paginação# Os filtros possíveis são: professional_id (id do profissional de saúde), patient_id (id do paciente),# movement_label (identificação do movimento), articulations (articulações incluídas no movimento)response=rebase_client.fetch_movements(professional_id='professional',patient_id='patient',page=1,per=10)print(f'Movimentos:{response.movements}')# Da mesma forma, as Sessões podem ser buscadas individualmente ou listadasresponse=rebase_client.find_session(id)print(f'Sessão:{response.session}')# Os filtros suportados pela listagem de Sessão são: professional_id e patient_id.# Também são aceitos os filtros movement_label e articulations, mas estes filtram os movimentos das Sessõesresponse=rebase_client.fetch_sessions(professional_id='professional',patient_id='patient',page=1,per=10)print(f'Sessões:{response.sessions}')Atualizando e deletando# São disponibilizados métodos para deletar e excluir Movimentos e Sessõesresponse=rebase_client.update_movement(updatedMovement)response=rebase_client.delete_movement(id)response=rebase_client.update_session(updatedSession)response=rebase_client.delete_session(id)Tópicos AvançadosA seguir, serão abordados dois assuntos relevantes para as requisições de listagem:filtragemepaginação.FiltragemAs requisições de listagem do ReBase, de Movimentos ou de Sessões, suportam alguns filtros, listados e explicados a seguir.Listagem de Movimentos:professional_id:recebe umastringque representa o ID do profissional de saúde responsável pelo Movimento;patient_id:recebe umastringque representa o ID do paciente que executou o Movimento;movement_label:recebe umastringque representa a propriedadelabeldo Movimento;articulations:recebe uma lista destringsque representam as articulações trabalhadas no Movimento.Listagem de Sessões:professional_id:recebe umastringque representa o ID do profissional de saúde responsável pela Sessão;patient_id:recebe umastringque representa o ID do paciente que avaliado durante a Sessão.A listagem de Sessões pode recebe ainda dois filtros adicionais. Estes, no entanto, não filtrarão a lista de Sessões em si, mas sim as listas de Movimentos das Sessões. São eles:movement_label:recebe umastringque representa a propriedadelabeldo Movimento;articulations:recebe uma lista destringsque representam as articulações trabalhadas no Movimento.Estes filtros podem ser úteis em alguns casos específicos. Um exemplo de uso: listar as Sessões de um paciente específico, mas incluir apenas os Movimentos que trabalharam um grupo específico de articulações.Vale notar, por fim, que todos os filtros sãoaditivos, ou seja, ao utilizarnmúltiplos filtros, serão retornados os documentos que satisfaçamtodosos filtros, ou seja, os documentos que satisfaçam o filtro 1Eo filtro 2E...Eo filtro n.PaginaçãoAs requisições de listagem, tanto de Movimentos quanto de Sessões, também suportam paginação. Utilizando paginação, elimina-se a necessidade de carregar todos os items de uma listagem de uma só vez, o que pode significar um ganho de velocidade e desempenho para uma aplicação. O ReBaseRS suporta dois tipos de paginação: baseada emper e pagee baseada emIDs.O primeiro tipo utiliza dois parâmetros:per, que representa a quantidade de itens presentes em cada página, epage, que representa qual página deve ser carregada. Desta forma, supondo que quiséssemos carregar 10 elementos por página, para carregar a primeira página usaríamos{ per: 10, page: 1 }e receberíamos os primeiros 10 itens da lista. Para carregar a segunda página usaríamos{ per: 10, page: 2 }e receberíamos os 10 itens seguintes e assim por diante. Este método é simples de se utilizar e de se entender e permite o carregamento de qualquer página, porém possui uma desvantagem: para recuperar uma páginan, é necessário recuperar todas as páginas anteriores, o que faz com que as requisições fiquem mais lentas conforme o númeronda página cresce. Para mitigar este problema, é possível utilizar a paginação baseada em IDs.A paginação baseada em IDs também depende de dois parâmetros:per, a quantidade de itens por página, eprevious_id, o ID do último item da página anterior. Pela forma como o banco de dados do ReBase é modelado, as listas de Movimentos e de Sessões são ordenadas pelos IDs dos documentos, que são sequenciais. Ou seja, se quisermos recuperar os 10 itens seguintes a um itemi, basta recuperar os primeiros 10 itens cujo ID seja maior do que o ID dei. Explorando essa característica, é possível implementar um método de paginação que permite que todas as páginas sejam recuperadas em tempos equivalentes. Desta forma, para recuperar a primeira página usaríamos{ per: 10, previous_id: null }, já que não existe uma página anterior. Supondo que o ID do último item da primeira página seja "ABC", para recuperar a segunda página usaríamos{ per: 10, previous_id: "ABC" }. Apesar de tudo, este método de paginação também tem uma desvantagem: para recuperar uma página específica, é necessário ter recuperado todas as páginas anteriores a ela, já que é preciso saber os IDs dos documentos que estão contidos nelas.Assim, cabe ao desenvolvedor analisar sua aplicação e decidir qual método de paginação deverá ser utilizado (ou se a paginação é mesmo necessária). Aplicações que devem permitir a qualquer momento o acesso a qualquer página, deverão usar a paginação baseada em per e page. Por outro lado, para uma aplicação que precisa exibir uma lista com scroll infinito, por exemplo, na qual os itens são carregados sequencialmente, se beneficiará mais do método baseado em IDs. Para mais informações,este artigopode ser útil.ExemplosEsta biblioteca inclui a pastaexamples, que inclui alguns códigos-exemplo básicos de utilização da API.Documentação CompletaA seguir, estão incluídas tabelas e descrições detalhando todas as classes e módulos da API Python ReBase.ReBaseClientEsta classe é responsável por toda a comunicação com o ReBaseRS. Seus métodos retornam objetos da classeAPIResponse. Exemplos de uso podem ser encontrados na seçãoQuick Start:. O ReBaseClient deve ser inicializado com o email e o token do usuários previamente cadastrados.Atributos:AtributoTipouser_emailstrEmail do usuáriouser_tokenstrToken de autenticação do usuárioMétodos:MétodoRetornoParâmetros__init__Noneuser_email: str, user_token: str, try_authenticate: bool = FalseMétodo de inicialização da classe. Recebe o endereço de email e o token de acesso do usuário. É possível tentar autenticar o usuário no momento da inicialização, passando o argumentotry_authenticate=True, porém, caso a autenticação falhe neste ponto, será lançado um erroUnauthorizedUserErrorauthenticateAPIResponseEnvia uma requisição de autenticação que não executa nenhum operação sobre o banco de dados. O envio desta requisição não é obrigatório, visto que todas as outras requisições também realizam autenticaçãofetch_movementsAPIResponseprofessional_id: str = "", patient_id: str = "", movementLabel: str = "", articulations: list = None, legacy: bool = False, page: int = 0, per: int = 0, previous_id: str = ""Recupera uma lista de Movimentos armazenados no ReBaseRS. Suporta diversos filtros e paginaçãofind_movementAPIResponseid: str, legacy: bool = FalseRecupera um Movimento específico a partir do ID. O parâmetrolegacy, seTrue, retorna o Movimento no formato antigo do ReBaseinsert_movementAPIResponsemovement:MovementInsere um Movimento no ReBaseupdate_movementAPIResponsemovement:MovementAtualiza um Movimento já existente no ReBasedelete_movementAPIResponseid: strExclui um Movimento do ReBasefetch_sessionsAPIResponseprofessional_id: str = "", patient_id: str = "", movement_label: str = "", articulations: list = None, legacy: bool = False, deep: bool = False, page: int = 0, per: int = 0, previous_id: str = ""Recupera uma lista de Sessões armazenadas no ReBaseRS. Suporta diversos filtros e paginação. O parâmetrolegacy, seTrue, retorna as Sessões no formato antigo do ReBase. Caso o parâmetrodeepsejaTrue, retorna também os Movimentos das Sessões, caso contrário, retorna apenas os IDs dos Movimentosfind_sessionAPIResponseid: str, legacy: bool = False, deep: bool = FalseRecupera uma Sessão específica a partir do ID. O parâmetrolegacy, seTrue, retorna a Sessão no formato antigo do ReBase. Caso o parâmetrodeepsejaTrue, retorna também os Movimentos da Sessão, caso contrário, retorna apenas os IDs dos Movimentosinsert_sessionAPIResponsesession:SessionInsere uma Sessão no ReBaseupdate_sessionAPIResponsesession:SessionAtualiza uma Sessão já existente no ReBasedelete_sessionAPIResponseid: str, deep: bool = FalseExclui uma Sessão do ReBase. Caso o parâmetrodeepsejaTrue, deleta também seus MovimentosMódulosutilO móduloutilcontém diversos métodos utilitários.Métodos:MétodoRetornoParâmetrosis_valid_strboolvalue: anyRetornaTruesevaluefor uma string válida (uma instância da classestr). Caso contrário, retornaFalseis_valid_numberboolvalue: anyRetornaTruesevaluefor um número válido (uma instância da classeintou da classefloat). Caso contrário, retornaFalseis_valid_idboolvalue: anyRetornaTruesevaluefor considerado um id válido para o ReBase (uma string válida não vazia ou um inteiro maior que 0). Caso contrário, retornaFalseis_valid_movement_fieldboolfield: str, value: anyRetornaTruesefieldfor um campo válido para um Movimento do ReBase e sevaluefor um valor válido para esse campo. RetornaFalsecaso contráriois_valid_session_fieldboolfield: str, value: anyRetornaTruesefieldfor um campo válido para um Movimento do ReBase e sevaluefor um valor válido para esse campo. RetornaFalsecaso contrárioexclude_keys_from_dictNonedictionary: dict, keys: listRemove uma dada lista de chaves de um dado dicionáriovalidate_initialization_dictNonevalidation_function: Callable[[str, any], bool], resource_name: str, field_rules: dict, dictionary: dictValida um dicionário de inicializaçãodictionarycom base nos campos definidos emfield_rulesutilizando a função de validaçãovalidation_function. Caso encontre algum campo inválido, lança umValueErrorcuja mensagem contém o nome apropriado do recursoresource_nameModelosAPIResponseA classe APIResponse modela uma resposta generalizada do servidor ReBaseRS.Atributos:AtributoTiporesponse_typeResponseType(Enum)Tipo da requisição enviada. Valores possíveis: { 0: FetchMovements, 1: FindMovement, 3: InsertMovement, 4: UpdateMovement, 5: DeleteMovement, 6: FetchSessions, 7: FindSession, 8: InsertSession, 9: UpdateSession, 10: DeleteSession, 11: APIError }statusintStatus da resposta. 0 representa sucesso e qualquer outro valor representa um errocodeintCódigo HTTP da resposta (E.g. 200, 201, 404, etc. )successboolDiz se a requisição foi bem sucedida ou não. Em outras palavras, diz se status == 0Métodos:MétodoRetornoParâmetroshas_databoolkey: strRetornaTruese o atributokeyestiver presente nos dados da resposta eFalsecaso contrárioget_databoolkey: strRetorna o valor do atributokeynos dados da resposta. Os possíveis atributos são: 'message', 'HTMLError', 'error', 'warning', 'movements', 'movement', 'sessions', 'session', 'deletedId', 'deletedCount'has_meta_databoolkey: strRetornaTruese o atributokeyestiver presente nos metadados da resposta eFalsecaso contrárioget_meta_databoolkey: strRetorna o valor do atributokeynos metadados da resposta. Os possíveis atributos são: 'current_page', 'next_page', 'total_count', 'total_page_count'MovementModela um Movimento do ReBase.Atributos:AtributoTipoidstrID do MovimentolabelstrLabel, ou etiqueta, de identificação do Movimento. Normalmente representa uma categoria ou grupo de MovimentosdescriptionstrDescrição do MovimentodevicestrDispositivo responsável pela captura do Movimento (E.g. Kinect, MediaPipe, etc.)fpsfloatQuantidade de quadros por segundo do MovimentodurationfloatDuração do Movimentonumber_of_registersintQuantidade de Registros presentes no Movimento (os Registros serão descritos a seguir)articulationslistArticulações utilizadas pelo Movimento. As Articulações são identificadas por strings arbitrárias definidas pelo usuário da API. Cabe a cada desenvolvedor definir e seguir seu padrão. Desta maneira, o ReBase pode armazenar movimentos com um conjunto variável de Articulaçõesinsertion_datestrData de inserção do Movimentoupdate_datestrData da última atualização do Movimentosession_idstrID da Sessão à qual o Movimento pertenceprofessional_idstrIdentificação do profissional da saúde responsável pela captura do Movimentoapp_codeintCódigo da aplicação que gerou o Movimento. Um inteiro positivo, maior que zero, arbitrário definido pelos desenvolvedores da aplicaçãoapp_datastrDados arbitrários utilizados pela aplicação que gerou o Movimento. Pode ser utilizado pelos usuários da API para armazenar dados no formato que quiserem, como um json ou uma stringpatient_idstrIdentificação anônima do paciente que realizou o Movimentoregisters[Register]Lista de Registros que representam o Movimento em si. Ao adicionar um registro a um Movimento, mesmo que ele seja um dicionário, será automaticamente convertido à classeRegisterMétodos:MétodoRetornoParâmetrosadd_registerNoneregister:RegisterAdiciona um novo Registro ao Movimentoto_dictdictexclude: listConverte o Movimento para um dicionário. Recebe uma lista de propriedades a serem ignoradasto_jsonstrupdate: bool = FalseConverte o Movimento para json. O parâmetro update modifica o json gerado: para requisições de criação use update comoFalsee para requisições de atualização use update comoTrueRegisterModela um Registro do ReBase, essencialmente um quadro, ou um frame, de um Movimento. Um Registro contém as rotações nos eixos x, y e z de cada Articulação do Movimento em um determinado instante. A classe Register se comporta como um dicionário, ou seja, cada articulação deve ser acessada através do operador[](ex:register['articulation1'] = Rotation(1.0, 2.0, 3.0))Atributos:AtributoTipoarticulation_countintA quantidade de Articulações presentes no Registroarticulationsreadonly listA lista das Articulações presentes no Registrois_emptyboolIndica se o registro está vazio, ou seja, não contem nenhuma ArticulaçãoMétodos:MétodoRetornoParâmetrosto_dictdictConverte o Registro em um dicionárioRotationRepresenta um conjunto de rotações de uma Articulação.Atributos:AtributoTipoxnumberA rotação no eixo XynumberA rotação no eixo YznumberA rotação no eixo ZMétodos:MétodoTipoParâmetrosto_listlistConverte a Rotação para uma listato_tupledictConverte a Rotação para uma tuplaSessionModela uma Sessão do ReBase.Atributos:AtributoTipoidstrID da SessãotitlestrTítulo da SessãodescriptionstrDescrição da Sessãoprofessional_idstrIdentificação do profissional de saúde responsável pela captura da Sessãopatient_session_numberintNúmero da Sessão do paciente (Ex.: 1 para a primeira Sessão, 2 para a segunda, etc.)insertion_datestrData de criação da Sessãoupdate_datestrData de atualização da Sessãopatient_idstrIdentificação anônima do paciente que realizou a Sessãopatient_ageintIdade do pacientepatient_heightfloatAltura do pacientepatient_weightfloatPeso do pacientemain_complaintstrQueixa principal do pacientehistory_of_current_diseasestrHistórico da condição atual do pacientehistory_of_past_diseasestrHistórico de condições anteriores do pacientediagnosisstrDiagnóstico dado ao paciente pelo profissional de saúderelated_diseasesstrCondições relacionadas à do pacientemedicationsstrMedicações das quais o paciente faz usophysical_evaluationstrAvaliação física do paciente realizada pelo profissionalnumber_of_movementsintNúmero de Movimentos pertencentes à SessãodurationfloatDuração total da Sessão. Equivale à soma das durações dos seus Movimentosmovements[Movement]Lista dos Movimentos pertencentes à SessãoMétodos:MétodoTipoParâmetrosto_dictdictexclude: list, movement_exclude: listConverte a Sessão para um dicionário. Recebe duas listas: uma lista de propriedades a serem ignoradas e uma outra lista de propriedades a serem ignoradas na conversão dos seus Movimentosto_jsonstrupdate: bool = FalseConverte a Sessão para json. O parâmetro update modifica o json gerado: para requisições de criação use update comoFalsee para requisições de atualização use update comoTrueErrosA biblioteca Python ReBase define alguns erros personalizados para os modelos de dados e casos de uso do ReBase. São eles:MismatchedArticulationsError:disparado ao criar um Movimento com Registros que tenham articulações diferentes das definidas no Movimento ou ao adicionar a um Movimento um Registro que tenha articulações diferentes das do Movimento;MissingAttributeError:disparado ao tentar enviar uma requisição ao ReBaseRS e algum parâmetro não tenha um atributo obrigatório;RepeatedArticulationError:disparado ao criar um Movimento ou um Registro com uma lista de articulações que contenha articulações repetidas.UnauthorizedUserError:disparado quando um objeto da classe ReBaseClient é inicializado com o parâmetrotry_authenticate=Truee a autenticação falha.ContatoTiago Trotta:mrtrotta2010@gmail.comDiego Dias:diegocolombodias@gmail.com