pdsharepoint 2.0.0
Pacote para obter arquivos excel ou listas do Sharepoint em um DataFrame pandas
Requires Python: >=3.8

# pdSharepoint: Integração Python com SharePoint

![Python](https://img.shields.io/badge/Python-3.9%2B-blue?style=for-the-badge&logo=python)
![Pandas](https://img.shields.io/badge/Pandas-2.x-blue?style=for-the-badge&logo=pandas)
![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)

O `pdSharepoint` é um pacote de elite, projetado para integrar o poder do `pandas` com a plataforma SharePoint. Ele permite a extração de listas e arquivos do SharePoint diretamente para DataFrames, além de realizar downloads de forma eficiente, utilizando um fluxo de autenticação não-interativo e seguro.

Este pacote utiliza o projeto [O365](https://pypi.org/project/O365/) como base para a comunicação com a API do Microsoft Graph.

---

## Tabela de Conteúdos

- [pdSharepoint: Integração Python com SharePoint](#pdsharepoint-integração-python-com-sharepoint)
  - [Tabela de Conteúdos](#tabela-de-conteúdos)
  - [1. Instalação](#1-instalação)
  - [2. Configuração de Autenticação](#2-configuração-de-autenticação)
  - [3. Como Usar](#3-como-usar)
    - [Inicializando o Cliente](#inicializando-o-cliente)
    - [Lendo uma Lista do SharePoint](#lendo-uma-lista-do-sharepoint)
    - [Lendo um Arquivo Excel](#lendo-um-arquivo-excel)
    - [Baixando um Arquivo](#baixando-um-arquivo)
  - [4. Contribuição](#4-contribuição)
  - [5. Licença](#5-licença)

---

## 1. Instalação

Para instalar as dependências necessárias, execute o comando abaixo. É imperativo que você utilize um ambiente virtual (`.venv`) para manter a ordem.

```shell
pip install pdSharepoint
```

## 2. Configuração de Autenticação

A autenticação é realizada via **Client Credentials Flow**, que não exige intervenção humana. Para isso, você precisa registrar uma aplicação no Azure AD e obter três informações cruciais: `Client ID`, `Client Secret` e `Tenant ID`.

<details>
<summary><strong>Clique para expandir o passo a passo de registro no Azure</strong></summary>

1. **Acesse o Portal do Azure** e navegue até **Azure Active Directory**.
2. Vá para **"Registros de aplicativo"** no menu à esquerda e selecione **"+ Novo registro"**.
3. **Dê um nome** à sua aplicação (e.g., `pdSharepoint_automacao`).
4. Em "Tipos de conta suportados", selecione **"Apenas contas neste diretório organizacional"**.
5. Clique em **"Registrar"**.
6. Na página de visão geral da sua aplicação, copie e guarde os seguintes valores:
    - **ID do Aplicativo (cliente)** -> `CLIENT_ID`
    - **ID do Diretório (locatário)** -> `TENANT_ID`
7. No menu à esquerda, vá para **"Certificados e segredos"**.
8. Clique em **"+ Novo segredo do cliente"**, dê uma descrição e clique em "Adicionar".
9. **Copie o "Valor" do segredo imediatamente**. Este é o seu `CLIENT_SECRET`. Ele não será exibido novamente.
10. No menu à esquerda, vá para **"Permissões de API"**.
11. Clique em **"+ Adicionar uma permissão"** e selecione **"Microsoft Graph"**.
12. Selecione **"Permissões de aplicativo"** (e não "Permissões delegadas").
13. Na barra de pesquisa, procure e adicione a seguinte permissão:
    - `Sites.ReadWrite.All` (ou `Sites.Selected` para um controle mais granular e seguro).
14. Clique em **"Adicionar permissões"**.
15. **IMPORTANTE:** De volta à tela de "Permissões de API", clique no botão **"Conceder consentimento de administrador para [Seu Diretório]"**. Você deve ter privilégios de administrador para fazer isso. Sem o consentimento do administrador, a autenticação falhará.

</details>

## 3. Como Usar

A utilização do pacote foi centralizada na classe `PdSharepoint` para maior eficiência e organização.

### Inicializando o Cliente

Primeiro, importe a classe. Crie uma instância de `PdSharepoint` fornecendo suas credenciais (`client_id`, `client_secret`) e o `tenant_id`.

```python
from pdSharepoint.scripts.core import PdSharepoint

# Suas credenciais obtidas no Azure
CLIENT_ID = 'seu-client-id-aqui'
CLIENT_SECRET = 'seu-client-secret-aqui'
TENANT_ID = 'seu-tenant-id-aqui'

CREDENTIALS = (CLIENT_ID, CLIENT_SECRET)
TOKEN_FILEPATH = 'seu-token-path-aqui'

# Inicialize o cliente
try:
    pds = PdSharepoint(credentials=CREDENTIALS, token_filepath=TOKEN_FILEPATH)
    print("Autenticação bem-sucedida.")
except RuntimeError as e:
    print(f"Falha na autenticação: {e}")

```

### Lendo uma Lista do SharePoint

Para ler uma lista e convertê-la em um DataFrame `pandas`, utilize o método `read_sharepoint_list`.

```python
HOST = 'seu_servidor.sharepoint.com'
SITE = 'NomeDoSeuSite'
LIST_NAME = 'NomeDaSuaLista'

try:
    df_lista = pds.read_sharepoint_list(
        host=HOST,
        site=SITE,
        list_name=LIST_NAME
    )
    print("Lista do SharePoint carregada com sucesso:")
    print(df_lista.head())

except Exception as e:
    print(f"Falha ao ler a lista: {e}")
```

### Lendo um Arquivo Excel

Para ler um arquivo Excel diretamente do SharePoint para um DataFrame, utilize `read_sharepoint_excel`. Quaisquer argumentos adicionais (`**kwargs`) serão passados para a função `pandas.read_excel`.

```python
HOST = 'seu_servidor.sharepoint.com'
SITE = 'NomeDoSeuSite'
LIBRARY = 'Documentos'
FILE_PATH_IN_SHAREPOINT = '/General/MeuArquivo.xlsx'

try:
    df_excel = pds.read_sharepoint_excel(
        host=HOST,
        site=SITE,
        library=LIBRARY,
        sharepoint_file_path=FILE_PATH_IN_SHAREPOINT,
        sheet_name='Vendas'  # Exemplo de kwarg para pd.read_excel
    )
    print("Arquivo Excel carregado com sucesso:")
    print(df_excel.head())

except Exception as e:
    print(f"Falha ao ler o arquivo Excel: {e}")
```

### Baixando um Arquivo

Para baixar qualquer arquivo de uma biblioteca do SharePoint para o seu sistema local, utilize `download_sharepoint_excel`.

```python
from pathlib import Path

HOST = 'seu_servidor.sharepoint.com'
SITE = 'NomeDoSeuSite'
LIBRARY = 'Documentos'
FILE_PATH_IN_SHAREPOINT = '/General/RelatorioAnual.xlsx'
LOCAL_FILENAME = Path('downloads/relatorio_2025.xlsx')

try:
    downloaded_path = pds.download_sharepoint_excel(
        host=HOST,
        site=SITE,
        library=LIBRARY,
        sharepoint_file_path=FILE_PATH_IN_SHAREPOINT,
        filename=LOCAL_FILENAME
    )
    print(f"Arquivo baixado com sucesso para: {downloaded_path}")

except Exception as e:
    print(f"Falha ao baixar o arquivo: {e}")
```

---

## 4. Contribuição

Contribuições para o Império são bem-vindas, desde que sigam os mais altos padrões. Consulte o arquivo `CONTRIBUTING.md` para as diretrizes de codificação.

## 5. Licença

Este projeto está sob a licença MIT. Veja o arquivo [LICENSE](LICENSE) para mais detalhes.