shade-plugins-google 0.1.0__py3-none-any.whl

shade_plugins_google/__init__.py

@@ -0,0 +1,513 @@
+"""O plugin ``google``: ler e escrever no Google Sheets e listar, baixar e enviar no Google Drive
+sob o contrato de plugin do shade-sdk, com o token OAuth da conexão da plataforma.
+
+```toml
+[hosts]
+permitidos = ["sheets.googleapis.com", "www.googleapis.com"]
+
+[conexoes]
+nomes = ["google-drive"]
+
+[plugins]
+google = "0.1.0"
+```
+
+```python
+import shade_plugins_google as google
+
+for pedido in google.ler_planilha("1AbC...", "Pedidos!A1:D"):
+    ...
+
+with item.efetivar("registrar na planilha"):
+    google.escrever_linha("1AbC...", "Pedidos!A1", [item["pedido"], item["cliente"], "ok"])
+
+with item.efetivar("guardar o comprovante"):
+    google.enviar_arquivo("comprovante.pdf", pasta="1XyZ...")
+```
+
+- **Conta:** a conexão ``google-drive`` da plataforma (Conectores). O robô nunca vê a senha nem
+  o refresh token: o token de acesso chega sob demanda e é renovado pela plataforma. No laptop,
+  ponha um token de acesso em ``SHADE_TOKEN_GOOGLE_DRIVE``.
+- **Escopo:** a conexão pede ``spreadsheets`` e ``drive.file``. Planilha: qualquer uma que a
+  conta veja. Drive: só o que o próprio app enviou (``enviar_arquivo``) ou que a conta abriu
+  com ele; o resto do Drive não aparece em ``listar_arquivos`` (devolve 404 em
+  ``baixar_arquivo``).
+- **Ler não muda nada:** ``ler_planilha``, ``listar_arquivos`` e ``baixar_arquivo`` rodam
+  inclusive no ensaio.
+- **Escrever só dentro de** ``item.efetivar()`` (no ensaio não roda):
+  - ``enviar_arquivo`` não duplica: o arquivo leva uma marca derivada da chave do item, do nome
+    da efetivação e da ordem do envio, e antes de criar o plugin procura a marca. A
+    retentativa e o "refazer" acham o que já subiu, enquanto a busca do Drive o enxergar (logo
+    depois de um envio sem confirmação ela pode atrasar: por isso a dúvida é ``GoogleIncerto``).
+  - ``escrever_linha`` acrescenta uma linha (``values.append``): o Sheets não reconhece
+    repetição, então o plugin só repete o que certamente não chegou (a rede que recusou, o
+    ``429``). Depois do envio, a dúvida vira ``GoogleIncerto`` e o item fica retido para
+    conferência. O texto vai cru (``RAW``): ``=HYPERLINK(...)`` entra como texto, nunca como
+    fórmula.
+- **Prazo:** ``timeout=`` (30 s) vale para a chamada inteira, retentativas incluídas.
+"""
+
+from __future__ import annotations
+
+import mimetypes
+import os
+import re
+import secrets
+import urllib.parse
+from pathlib import Path
+from typing import Any
+
+from shade_sdk import http
+from shade_sdk.plugins import Plugin
+
+from shade_plugins_google import _cliente
+from shade_plugins_google._cliente import CONEXAO, DRIVE, SHEETS, Cliente, Prazo
+from shade_plugins_google.erros import ErroDoGoogle, GoogleIncerto, GoogleNaoSaiu, NaoEncontrado
+
+__version__ = "0.1.0"
+
+#: Quantos arquivos ``listar_arquivos`` devolve, no máximo, e quantos o Drive dá por página.
+LIMITE_MAX = 10_000
+POR_PAGINA = 100
+#: O teto de um download.
+ARQUIVO_MAX = 1024 * 1024 * 1024
+#: O teto de um envio: o upload ``multipart`` do Drive é para arquivos de até 5 MB.
+ENVIO_MAX = 5 * 1024 * 1024
+#: A propriedade privada do app que marca o arquivo enviado com a chave da chamada.
+MARCA = "shade_idempotencia"
+#: O id de planilha, arquivo e pasta do Google: letras, dígitos, ``-`` e ``_``.
+_ID = re.compile(r"^[A-Za-z0-9_-]{1,200}$")
+_CONTROLE = re.compile(r"[\x00-\x1f\x7f]")
+#: O tipo MIME (``application/pdf``): vai num cabeçalho da parte do upload.
+_MIME = re.compile(
+    r"^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]{0,63}/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]{0,126}$"
+)
+#: O prefixo dos arquivos nativos do Google (Docs, Sheets, Slides), que não se baixam como são.
+_NATIVO = "application/vnd.google-apps."
+_CAMPOS_DO_ARQUIVO = "id,name,mimeType,size,modifiedTime,parents"
+
+PLUGIN = Plugin(
+    "google",
+    __version__,
+    shade_sdk=">=0.22.3,<0.23",
+    dono="Equipe de integrações da ShadeOne",
+    hosts=[SHEETS, DRIVE],
+    conexoes=[CONEXAO],
+)
+
+__all__ = [
+    "PLUGIN",
+    "ErroDoGoogle",
+    "GoogleIncerto",
+    "GoogleNaoSaiu",
+    "NaoEncontrado",
+    "baixar_arquivo",
+    "enviar_arquivo",
+    "escrever_linha",
+    "ler_planilha",
+    "listar_arquivos",
+]
+
+
+# ── as réguas ─────────────────────────────────────────────────────────────────────────────
+
+
+def _id(valor: Any, campo: str) -> str:
+    if not isinstance(valor, str) or not _ID.fullmatch(valor):
+        raise ValueError(f"{campo} é o id do Google (letras, dígitos, '-' e '_'), como na URL")
+    return valor
+
+
+def _intervalo(valor: Any) -> str:
+    """O intervalo em notação A1 (``Pedidos!A1:D``): vai codificado no caminho, inteiro."""
+    if not isinstance(valor, str) or not valor.strip() or len(valor) > 500:
+        raise ValueError("intervalo é a notação A1, como 'Pedidos!A1:D' (até 500 caracteres)")
+    if _CONTROLE.search(valor):
+        raise ValueError("intervalo não pode ter quebra de linha nem caractere de controle")
+    return urllib.parse.quote(valor, safe="")
+
+
+def _porta(porta: Any) -> int | None:
+    if porta is not None and (
+        not isinstance(porta, int) or isinstance(porta, bool) or not 0 < porta < 65536
+    ):
+        raise ValueError(f"porta é um número de 1 a 65535, não {porta!r}")
+    return porta
+
+
+def literal_do_drive(valor: str) -> str:
+    """O texto como literal da consulta do Drive (``q``): entre aspas simples, com ``\\`` e
+    ``'`` escapados por ``\\`` (a regra da API). A barra vem primeiro, para a barra que o valor
+    traz não escapar a aspa que a regra acrescenta."""
+    if not isinstance(valor, str) or _CONTROLE.search(valor):
+        raise ValueError("o texto da busca não pode ter quebra de linha nem caractere de controle")
+    return "'" + valor.replace("\\", "\\\\").replace("'", "\\'") + "'"
+
+
+def _celula(valor: Any) -> Any:
+    if valor is None:
+        return ""
+    if isinstance(valor, bool | int | float | str):
+        return valor
+    raise TypeError(f"a célula é texto, número, booleano ou None, não {type(valor).__name__}")
+
+
+def _arquivo_do_workdir(caminho: Any) -> Path:
+    if not isinstance(caminho, str | os.PathLike):
+        raise TypeError("arquivo é o caminho de um arquivo do diretório de trabalho")
+    relativo = Path(caminho)
+    raiz = Path.cwd().resolve()
+    completo = (raiz / relativo).resolve()
+    if relativo.is_absolute() or completo != raiz and raiz not in completo.parents:
+        raise ValueError("arquivo é um caminho dentro do diretório de trabalho")
+    if not completo.is_file():
+        raise FileNotFoundError("arquivo: não existe no diretório de trabalho")
+    return completo
+
+
+def _pasta_relativa(pasta: Any) -> Path:
+    if not isinstance(pasta, str) or not pasta or _CONTROLE.search(pasta):
+        raise ValueError("pasta é um caminho relativo do diretório de trabalho")
+    partes = pasta.split("/")
+    if pasta.startswith("/") or any(p in ("", ".", "..") for p in partes):
+        raise ValueError("pasta é um caminho relativo, sem '..' nem segmento vazio")
+    return Path(pasta)
+
+
+def _nome_de_arquivo(nome: str) -> str:
+    limpo = _CONTROLE.sub("_", nome.replace("/", "_").replace("\\", "_")).strip(". ")
+    return (limpo or "arquivo")[:200]
+
+
+def _arquivo(dados: dict[str, Any]) -> dict[str, Any]:
+    tamanho = dados.get("size")
+    return {
+        "id": dados.get("id", ""),
+        "nome": dados.get("name", ""),
+        "tipo": dados.get("mimeType", ""),
+        "tamanho": int(tamanho) if isinstance(tamanho, str) and tamanho.isdigit() else None,
+        "modificado": dados.get("modifiedTime", ""),
+        "pastas": list(dados.get("parents") or []),
+    }
+
+
+def _lendo(operacao: str, funcao: Any) -> Any:
+    """A falha de rede no meio da leitura vira ``ErroDoGoogle``."""
+    try:
+        return funcao()
+    except ErroDoGoogle:
+        raise
+    except OSError as exc:
+        raise _cliente.falha_de_leitura(operacao, exc) from exc
+
+
+def _cliente_da_chamada(chamada: Any, porta: Any) -> Cliente:
+    return Cliente(chamada=chamada, prazo=Prazo(chamada.timeout), porta=_porta(porta))
+
+
+# ── Sheets ────────────────────────────────────────────────────────────────────────────────
+
+
+@PLUGIN.operacao
+def ler_planilha(
+    chamada: Any,
+    planilha: str,
+    intervalo: str,
+    *,
+    cabecalho: bool = True,
+    porta: int | None = None,
+) -> list[Any]:
+    """As linhas de ``intervalo`` (``Pedidos!A1:D``) da planilha ``planilha`` (o id da URL),
+    como a planilha as mostra (o valor formatado). Com ``cabecalho`` (o padrão), a primeira linha
+    dá os nomes e cada linha seguinte vira um ``dict`` (célula vazia no fim da linha vira
+    ``""``); sem ele, cada linha é uma lista. ``NaoEncontrado`` se a planilha ou a aba não
+    existe ou a conta não a vê."""
+    caminho = f"/v4/spreadsheets/{_id(planilha, 'planilha')}/values/{_intervalo(intervalo)}"
+    cliente = _cliente_da_chamada(chamada, porta)
+
+    def ler() -> list[Any]:
+        resposta = cliente.pedir("GET", SHEETS, caminho, parametros={"majorDimension": "ROWS"})
+        _cliente.checar_leitura("ler_planilha", resposta)
+        linhas = resposta.json().get("values") or []
+        if not cabecalho:
+            return [list(linha) for linha in linhas]
+        if not linhas:
+            return []
+        nomes = [str(n).strip() or f"coluna_{i + 1}" for i, n in enumerate(linhas[0])]
+        repetidos = sorted({n for n in nomes if nomes.count(n) > 1})
+        if repetidos:
+            raise ErroDoGoogle(f"Google ler_planilha: o cabeçalho repete {repetidos}")
+        return [
+            {nome: (linha[i] if i < len(linha) else "") for i, nome in enumerate(nomes)}
+            for linha in linhas[1:]
+        ]
+
+    return _lendo("ler_planilha", ler)
+
+
+@PLUGIN.efeito
+def escrever_linha(
+    chamada: Any,
+    planilha: str,
+    intervalo: str,
+    valores: list[Any] | tuple[Any, ...],
+    *,
+    porta: int | None = None,
+) -> dict[str, Any]:
+    """Acrescenta uma linha depois da tabela de ``intervalo`` (``Pedidos!A1``), só dentro de
+    ``item.efetivar()``. Cada valor é texto, número, booleano ou ``None`` (célula vazia), e vai
+    cru: o texto ``=SOMA(A1:A9)`` entra como texto, nunca como fórmula. Devolve ``intervalo`` (o
+    que foi escrito, como ``Pedidos!A7:C7``).
+
+    O Sheets não reconhece repetição: o plugin só repete o que certamente não chegou.
+    ``GoogleNaoSaiu`` (um ``http.NadaSaiu``): o Google recusou ou a rede não abriu.
+    ``GoogleIncerto``: o pedido foi e a confirmação não veio; a linha pode ter entrado."""
+    if not isinstance(valores, list | tuple) or not valores:
+        raise ValueError("valores é a lista das células da linha")
+    linha = [_celula(v) for v in valores]
+    caminho = f"/v4/spreadsheets/{_id(planilha, 'planilha')}/values/{_intervalo(intervalo)}:append"
+    cliente = _cliente_da_chamada(chamada, porta)
+    try:
+        resposta = cliente.pedir(
+            "POST",
+            SHEETS,
+            caminho,
+            parametros={"valueInputOption": "RAW", "insertDataOption": "INSERT_ROWS"},
+            corpo=_json({"majorDimension": "ROWS", "values": [linha]}),
+            tipo="application/json",
+            idempotencia=chamada.idempotencia,
+            repetir_depois_do_envio=False,
+        )
+    except OSError as exc:
+        raise _cliente.falha_de_escrita("escrever_linha", exc) from exc
+    _cliente.checar_escrita("escrever_linha", resposta)
+    atualizado = (resposta.json().get("updates") or {}).get("updatedRange", "")
+    return {"intervalo": atualizado if isinstance(atualizado, str) else ""}
+
+
+# ── Drive ─────────────────────────────────────────────────────────────────────────────────
+
+
+@PLUGIN.operacao
+def listar_arquivos(
+    chamada: Any,
+    *,
+    pasta: str | None = None,
+    nome: str | None = None,
+    tipo: str | None = None,
+    limite: int = POR_PAGINA,
+    porta: int | None = None,
+) -> list[dict[str, Any]]:
+    """Os arquivos do Drive que a conexão vê (fora da lixeira), até ``limite``: os de dentro de
+    ``pasta`` (o id), com ``nome`` no nome e do ``tipo`` (o MIME, como ``application/pdf``).
+    Cada um: ``id``, ``nome``, ``tipo``, ``tamanho`` (``None`` nos nativos do Google),
+    ``modificado`` e ``pastas``."""
+    if not isinstance(limite, int) or isinstance(limite, bool) or not 0 < limite <= LIMITE_MAX:
+        raise ValueError(f"limite é um número de 1 a {LIMITE_MAX}")
+    filtros = ["trashed = false"]
+    if pasta is not None:
+        filtros.append(f"{literal_do_drive(_id(pasta, 'pasta'))} in parents")
+    if nome is not None:
+        filtros.append(f"name contains {literal_do_drive(nome)}")
+    if tipo is not None:
+        filtros.append(f"mimeType = {literal_do_drive(tipo)}")
+    cliente = _cliente_da_chamada(chamada, porta)
+    return _lendo("listar_arquivos", lambda: _buscar(cliente, " and ".join(filtros), limite))
+
+
+def _buscar(cliente: Cliente, consulta: str, limite: int, **pedido: Any) -> list[dict[str, Any]]:
+    arquivos: list[dict[str, Any]] = []
+    pagina: str | None = None
+    while len(arquivos) < limite:
+        parametros = {
+            "q": consulta,
+            "fields": f"nextPageToken,files({_CAMPOS_DO_ARQUIVO})",
+            "pageSize": str(min(POR_PAGINA, limite - len(arquivos))),
+            "spaces": "drive",
+        }
+        if pagina:
+            parametros["pageToken"] = pagina
+        resposta = cliente.pedir("GET", DRIVE, "/drive/v3/files", parametros=parametros, **pedido)
+        _cliente.checar_leitura("listar_arquivos", resposta)
+        dados = resposta.json()
+        arquivos += [_arquivo(f) for f in dados.get("files") or [] if isinstance(f, dict)]
+        pagina = dados.get("nextPageToken")
+        if not isinstance(pagina, str) or not pagina:
+            break
+    return arquivos[:limite]
+
+
+@PLUGIN.operacao
+def baixar_arquivo(
+    chamada: Any,
+    arquivo: str,
+    *,
+    pasta: str = "google",
+    porta: int | None = None,
+) -> dict[str, Any]:
+    """Grava o arquivo ``arquivo`` (o id) em ``<pasta>/<nome>`` no diretório de trabalho (o nome
+    do Drive, limpo de separador e controle) e devolve ``id``, ``arquivo`` (o caminho gravado),
+    ``tamanho`` e ``tipo``. O arquivo só aparece inteiro: o download que cai no meio não deixa
+    arquivo. Os nativos do Google (Docs, Planilhas) não se baixam: leia a planilha com
+    ``ler_planilha``."""
+    identificador = _id(arquivo, "arquivo")
+    destino = _pasta_relativa(pasta)
+    cliente = _cliente_da_chamada(chamada, porta)
+    caminho = f"/drive/v3/files/{identificador}"
+    raiz = Path.cwd().resolve()
+
+    def ler() -> dict[str, Any]:
+        resposta = cliente.pedir("GET", DRIVE, caminho, parametros={"fields": _CAMPOS_DO_ARQUIVO})
+        _cliente.checar_leitura("baixar_arquivo", resposta)
+        dados = _arquivo(resposta.json())
+        if dados["tipo"].startswith(_NATIVO):
+            raise ErroDoGoogle(
+                "Google baixar_arquivo: é um arquivo nativo do Google (Docs, Planilhas), que não "
+                "se baixa como é; a planilha se lê com ler_planilha"
+            )
+        pasta_completa = raiz / destino
+        pasta_completa.mkdir(parents=True, exist_ok=True)
+        gravado = pasta_completa / _nome_de_arquivo(str(dados["nome"]))
+        parcial = pasta_completa / (gravado.name + ".parcial")
+        try:
+            conteudo = cliente.pedir(
+                "GET",
+                DRIVE,
+                caminho,
+                parametros={"alt": "media"},
+                para_arquivo=parcial,
+                tamanho_max=ARQUIVO_MAX,
+            )
+            if not 200 <= conteudo.status < 300:
+                _cliente.checar_leitura("baixar_arquivo", conteudo)
+            parcial.replace(gravado)
+        finally:
+            parcial.unlink(missing_ok=True)
+        return {
+            "id": identificador,
+            "arquivo": str(gravado.relative_to(raiz)),
+            "tamanho": conteudo.tamanho,
+            "tipo": dados["tipo"],
+        }
+
+    return _lendo("baixar_arquivo", ler)
+
+
+@PLUGIN.efeito
+def enviar_arquivo(
+    chamada: Any,
+    arquivo: str | os.PathLike[str],
+    *,
+    nome: str | None = None,
+    pasta: str | None = None,
+    tipo: str | None = None,
+    porta: int | None = None,
+) -> dict[str, Any]:
+    """Envia um arquivo do diretório de trabalho (até 5 MB) para o Drive, só dentro de
+    ``item.efetivar()``: na ``pasta`` (o id; sem ela, na raiz do Drive da conta), com ``nome``
+    (o do arquivo, se omitido) e o ``tipo`` (o MIME, adivinhado pelo nome). Devolve ``id``,
+    ``nome`` e ``reaproveitado`` (``True`` quando o arquivo desta mesma chamada já estava lá).
+
+    Não duplica: o arquivo leva a marca da chamada (a chave do item, o nome da efetivação e a
+    ordem do envio no bloco), e antes de criar o plugin procura a marca. ``GoogleNaoSaiu``: nada
+    foi enviado (o Google recusou, a rede não abriu, a busca não respondeu). ``GoogleIncerto``:
+    um envio saiu sem confirmação e as tentativas acabaram sem achar o arquivo; depois dele,
+    nenhuma falha seguinte vira ``GoogleNaoSaiu``."""
+    caminho = _arquivo_do_workdir(arquivo)
+    nome_final = nome if nome is not None else caminho.name
+    if not isinstance(nome_final, str) or not nome_final.strip() or _CONTROLE.search(nome_final):
+        raise ValueError("nome é o nome do arquivo no Drive, sem quebra de linha nem controle")
+    if pasta is not None:
+        _id(pasta, "pasta")
+    if tipo is not None and (not isinstance(tipo, str) or not _MIME.fullmatch(tipo)):
+        raise ValueError("tipo é o MIME, como 'application/pdf'")
+    tipo = tipo or mimetypes.guess_type(nome_final)[0] or "application/octet-stream"
+    dados = caminho.read_bytes()
+    if len(dados) > ENVIO_MAX:
+        raise ValueError("arquivo passa de 5 MB: o envio desta versão é de um pedido só")
+    marca = chamada.idempotencia
+    cliente = _cliente_da_chamada(chamada, porta)
+    consulta = (
+        f"appProperties has {{ key={literal_do_drive(MARCA)} and "
+        f"value={literal_do_drive(marca)} }} and trashed = false"
+    )
+    metadados: dict[str, Any] = {
+        "name": nome_final,
+        "mimeType": tipo,
+        "appProperties": {MARCA: marca},
+    }
+    if pasta is not None:
+        metadados["parents"] = [pasta]
+    fronteira = "shade-" + secrets.token_hex(16)
+    corpo = _multipart(fronteira, metadados, tipo, dados)
+    incerto: GoogleIncerto | None = None
+    for _ in range(_cliente.TENTATIVAS):
+        try:
+            return _enviar_uma_vez(cliente, consulta, marca, corpo, fronteira)
+        except GoogleIncerto as exc:
+            # O pedido pode ter criado: a volta seguinte procura a marca antes de criar de novo.
+            incerto = exc
+            if not cliente.prazo.cabe(0):
+                break
+        except Exception as exc:
+            # Depois de um envio sem confirmação, nenhuma falha seguinte (a busca que não abriu,
+            # o 4xx, o token que não veio) diz que nada saiu: a dúvida da volta anterior segue.
+            if incerto is not None:
+                raise incerto from exc
+            raise
+    assert incerto is not None
+    raise incerto
+
+
+def _enviar_uma_vez(
+    cliente: Cliente, consulta: str, marca: str, corpo: bytes, fronteira: str
+) -> dict[str, Any]:
+    """Uma volta do envio: procura a marca e, sem ela, cria. ``GoogleNaoSaiu`` quando esta volta
+    certamente não criou nada; ``GoogleIncerto`` quando pode ter criado."""
+    try:
+        achados = _buscar(cliente, consulta, 1, idempotencia=marca)
+    except (ErroDoGoogle, OSError) as exc:
+        # Sem a busca, não se cria (o token que não veio já é um ``http.NadaSaiu``).
+        raise GoogleNaoSaiu(f"Google enviar_arquivo: a busca da marca falhou: {exc}") from exc
+    if achados:
+        return {"id": achados[0]["id"], "nome": achados[0]["nome"], "reaproveitado": True}
+    try:
+        resposta = cliente.pedir(
+            "POST",
+            DRIVE,
+            "/upload/drive/v3/files",
+            parametros={"uploadType": "multipart", "fields": "id,name"},
+            corpo=corpo,
+            tipo=f"multipart/related; boundary={fronteira}",
+            idempotencia=marca,
+            repetir_depois_do_envio=False,
+        )
+    except OSError as exc:
+        raise _cliente.falha_de_escrita("enviar_arquivo", exc) from exc
+    _cliente.checar_escrita("enviar_arquivo", resposta)
+    try:
+        criado = resposta.json()
+    except ErroDoGoogle as exc:
+        raise GoogleIncerto(
+            "Google enviar_arquivo: o Drive confirmou com um corpo ilegível; o arquivo pode estar "
+            "lá com a marca desta chamada",
+            status=resposta.status,
+        ) from exc
+    return {"id": criado.get("id", ""), "nome": criado.get("name", ""), "reaproveitado": False}
+
+
+def _json(dados: Any) -> bytes:
+    import json
+
+    return json.dumps(dados, ensure_ascii=False).encode("utf-8")
+
+
+def _multipart(fronteira: str, metadados: dict[str, Any], tipo: str, dados: bytes) -> bytes:
+    """O corpo ``multipart/related`` do upload do Drive: os metadados em JSON e o conteúdo. A
+    fronteira é aleatória e o JSON é serializado (nenhum texto do robô monta a estrutura)."""
+    inicio = (f"--{fronteira}\r\nContent-Type: application/json; charset=UTF-8\r\n\r\n").encode(
+        "ascii"
+    )
+    meio = f"\r\n--{fronteira}\r\nContent-Type: {tipo}\r\n\r\n".encode("latin-1")
+    fim = f"\r\n--{fronteira}--\r\n".encode("ascii")
+    return inicio + _json(metadados) + meio + dados + fim

shade_plugins_google/_cliente.py

@@ -0,0 +1,288 @@
+"""O cliente HTTP das APIs do Google: o token da conexão, o prazo da chamada e a retentativa.
+
+Fala com ``sheets.googleapis.com`` e ``www.googleapis.com`` (os hosts que o plugin declara),
+com ``chamada.destino(host)`` antes de conectar. O certificado é verificado; o ``HTTPS_PROXY`` do
+ambiente é respeitado (no sandbox, o proxy da allowlist). Não segue redirecionamento: o token
+não vai a outro host.
+
+O token vem de ``chamada.token(CONEXAO)``. O ``401`` (o token expirou ou foi revogado antes da
+hora) troca o token uma vez (``renovar=True``) e repete: o pedido recusado não teve efeito.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import ssl
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from shade_sdk import http
+
+from shade_plugins_google.erros import ErroDoGoogle, GoogleIncerto, GoogleNaoSaiu, NaoEncontrado
+
+#: A conexão OAuth da plataforma de que o plugin pede o token (o provedor do catálogo).
+CONEXAO = "google-drive"
+SHEETS = "sheets.googleapis.com"
+DRIVE = "www.googleapis.com"
+#: Quantas vezes o pedido é tentado quando a rede ou o Google falham de forma transitória.
+TENTATIVAS = 3
+#: A espera antes da 2ª e da 3ª tentativa (a régua do ``shade_sdk.http``).
+ESPERAS = (0.5, 1.0)
+#: O teto do corpo de uma resposta que o plugin lê na memória (a planilha, a listagem).
+RESPOSTA_MAX = 16 * 1024 * 1024
+BLOCO = 1024 * 1024
+#: O motivo que o Google põe no erro, como vai para a mensagem.
+_MOTIVO = re.compile(r"^[A-Za-z_]{1,64}$")
+
+
+class Prazo:
+    """O ``timeout`` da chamada como um prazo só: cada etapa usa o que sobrou."""
+
+    def __init__(self, segundos: float) -> None:
+        self.fim = time.monotonic() + segundos
+
+    def restante(self) -> float:
+        sobra = self.fim - time.monotonic()
+        if sobra <= 0:
+            raise TimeoutError("o prazo da chamada acabou")
+        return sobra
+
+    def cabe(self, espera: float) -> bool:
+        return self.fim - time.monotonic() > espera
+
+
+class _SemRedirecionamento(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *args: Any, **kwargs: Any) -> None:
+        return None
+
+
+def _abridor() -> Callable[..., Any]:
+    contexto = ssl.create_default_context()
+    contexto.minimum_version = ssl.TLSVersion.TLSv1_2
+    return urllib.request.build_opener(
+        urllib.request.ProxyHandler(),
+        urllib.request.HTTPSHandler(context=contexto),
+        _SemRedirecionamento(),
+    ).open
+
+
+@dataclass
+class Resposta:
+    status: int
+    cabecalhos: Mapping[str, str]
+    corpo: bytes = b""
+    #: Onde o corpo foi gravado, quando o pedido pediu ``para_arquivo``.
+    arquivo: Path | None = None
+    tamanho: int = 0
+    motivo: str = field(default="")
+
+    def json(self) -> Any:
+        try:
+            return json.loads(self.corpo)
+        except ValueError as exc:
+            raise ErroDoGoogle("Google: a resposta não é JSON", status=self.status) from exc
+
+
+def motivo_do_erro(corpo: bytes) -> str:
+    """O motivo do erro do Google (``error.status`` ou ``error.errors[0].reason``), só se for um
+    nome curto: nunca o texto da mensagem, que pode repetir o pedido."""
+    try:
+        erro = json.loads(corpo[:65536]).get("error") or {}
+    except (ValueError, AttributeError):
+        return ""
+    candidatos = [erro.get("status")]
+    detalhes = erro.get("errors")
+    if isinstance(detalhes, list) and detalhes and isinstance(detalhes[0], dict):
+        candidatos.append(detalhes[0].get("reason"))
+    for candidato in candidatos:
+        if isinstance(candidato, str) and _MOTIVO.fullmatch(candidato):
+            return candidato
+    return ""
+
+
+def transitorio(exc: BaseException) -> bool:
+    """Falha de rede em que repetir pode dar certo. O certificado inválido e o prazo esgotado,
+    não."""
+    if isinstance(exc, TimeoutError):
+        return False
+    return isinstance(exc, urllib.error.URLError | ConnectionError | ssl.SSLError) and not (
+        isinstance(exc, urllib.error.URLError)
+        and isinstance(exc.reason, ssl.SSLCertVerificationError)
+    )
+
+
+@dataclass
+class Cliente:
+    chamada: Any
+    prazo: Prazo
+    porta: int | None = None
+    _token: str | None = None
+    _renovou: bool = False
+
+    def url(self, host: str, caminho: str, parametros: Mapping[str, str] | None = None) -> str:
+        endereco = host if self.porta in (None, 443) else f"{host}:{self.porta}"
+        consulta = urllib.parse.urlencode(dict(parametros or {}), quote_via=urllib.parse.quote)
+        return f"https://{endereco}{caminho}" + (f"?{consulta}" if consulta else "")
+
+    def _bearer(self, *, renovar: bool = False) -> str:
+        if self._token is None or renovar:
+            self._token = self.chamada.token(CONEXAO, renovar=renovar)
+        return self._token
+
+    def pedir(
+        self,
+        metodo: str,
+        host: str,
+        caminho: str,
+        *,
+        parametros: Mapping[str, str] | None = None,
+        corpo: bytes | None = None,
+        tipo: str | None = None,
+        para_arquivo: Path | None = None,
+        tamanho_max: int = RESPOSTA_MAX,
+        idempotencia: str | None = None,
+        repetir_depois_do_envio: bool = True,
+    ) -> Resposta:
+        """Um pedido com o token da conexão, dentro do prazo. Repete a falha transitória de rede,
+        o ``429`` e o ``5xx`` quando ``repetir_depois_do_envio`` (a leitura); senão, só o que
+        certamente não saiu (a rede que recusou antes do envio, o ``429``). O ``401`` troca o
+        token uma vez e repete. ``idempotencia`` vai no ``Idempotency-Key``, como o
+        ``shade_sdk.http`` faz nas escritas: o Google o ignora, e quem observa o tráfego (o proxy,
+        o servidor falso) distingue a execução."""
+        self.chamada.destino(host)
+        url = self.url(host, caminho, parametros)
+        abrir = _abridor()
+        ultima_falha: BaseException | None = None
+        ultima_resposta: Resposta | None = None
+        tentativa = 0
+        while tentativa < TENTATIVAS:
+            if tentativa:
+                espera = ESPERAS[min(tentativa - 1, len(ESPERAS) - 1)]
+                if not self.prazo.cabe(espera):
+                    break
+                time.sleep(espera)
+            tentativa += 1
+            cabecalhos = {"Authorization": f"Bearer {self._bearer()}", "Accept": "application/json"}
+            if tipo:
+                cabecalhos["Content-Type"] = tipo
+            if idempotencia:
+                cabecalhos["Idempotency-Key"] = idempotencia
+            pedido = urllib.request.Request(url, data=corpo, headers=cabecalhos, method=metodo)
+            try:
+                resposta = self._despachar(abrir, pedido, para_arquivo, tamanho_max)
+            except Exception as exc:
+                if not transitorio(exc) or not (repetir_depois_do_envio or http.nada_saiu(exc)):
+                    raise
+                ultima_falha, ultima_resposta = exc, None
+                continue
+            if resposta.status == 401 and not self._renovou:
+                # O token venceu antes da hora ou foi revogado: o pedido não teve efeito.
+                self._renovou = True
+                self._bearer(renovar=True)
+                tentativa -= 1
+                continue
+            if resposta.status == 429 or (resposta.status >= 500 and repetir_depois_do_envio):
+                ultima_falha, ultima_resposta = None, resposta
+                continue
+            return resposta
+        if ultima_resposta is not None:
+            return ultima_resposta
+        if ultima_falha is None:
+            raise TimeoutError("o prazo da chamada acabou")
+        raise ultima_falha
+
+    def _despachar(
+        self, abrir: Callable[..., Any], pedido: Any, para_arquivo: Path | None, tamanho_max: int
+    ) -> Resposta:
+        try:
+            with abrir(pedido, timeout=self.prazo.restante()) as resposta:
+                return self._ler(resposta, resposta.status, para_arquivo, tamanho_max)
+        except urllib.error.HTTPError as exc:
+            corpo = exc.read(65536) if exc.fp else b""
+            return Resposta(
+                exc.code, dict(exc.headers.items()), corpo, motivo=motivo_do_erro(corpo)
+            )
+
+    def _ler(
+        self, resposta: Any, status: int, para_arquivo: Path | None, tamanho_max: int
+    ) -> Resposta:
+        cabecalhos = dict(resposta.headers.items())
+        if para_arquivo is None:
+            corpo = resposta.read(tamanho_max + 1)
+            if len(corpo) > tamanho_max:
+                raise ErroDoGoogle("Google: a resposta passa do teto de leitura")
+            return Resposta(status, cabecalhos, corpo, tamanho=len(corpo))
+        tamanho = 0
+        with para_arquivo.open("wb") as saida:
+            while bloco := resposta.read(BLOCO):
+                tamanho += len(bloco)
+                if tamanho > tamanho_max:
+                    raise ErroDoGoogle("Google: o arquivo passa do teto de download")
+                saida.write(bloco)
+                self.prazo.restante()
+        esperado = cabecalhos.get("Content-Length", "")
+        if esperado.isdigit() and int(esperado) != tamanho:
+            # O ``read`` devolve vazio, sem levantar, quando a conexão cai no meio do corpo.
+            raise ErroDoGoogle(
+                f"Google: o download veio incompleto ({tamanho} de {esperado} bytes)"
+            )
+        return Resposta(status, cabecalhos, arquivo=para_arquivo, tamanho=tamanho)
+
+
+def _descricao(resposta: Resposta) -> str:
+    return f"{resposta.status} {resposta.motivo}".strip()
+
+
+def checar_leitura(operacao: str, resposta: Resposta) -> None:
+    if 200 <= resposta.status < 300:
+        return
+    if resposta.status == 404:
+        raise NaoEncontrado(
+            f"Google {operacao}: não existe, ou a conta conectada não o vê "
+            f"({_descricao(resposta)}); no Drive, o app vê só o que enviou ou o que a conta "
+            "abriu com ele",
+            status=404,
+        )
+    if resposta.status == 403:
+        raise ErroDoGoogle(
+            f"Google {operacao}: a conta conectada não tem permissão ({_descricao(resposta)}); "
+            "compartilhe a planilha ou o arquivo com ela",
+            status=403,
+        )
+    raise ErroDoGoogle(
+        f"Google {operacao}: o Google devolveu {_descricao(resposta)}", status=resposta.status
+    )
+
+
+def checar_escrita(operacao: str, resposta: Resposta) -> None:
+    if 200 <= resposta.status < 300:
+        return
+    if 400 <= resposta.status < 500:
+        # O 429 também: o Google limitou antes de aplicar, e o cliente já tentou de novo.
+        raise GoogleNaoSaiu(
+            f"Google {operacao}: o Google recusou o pedido ({_descricao(resposta)})",
+            status=resposta.status,
+        )
+    raise GoogleIncerto(
+        f"Google {operacao}: o Google devolveu {_descricao(resposta)}", status=resposta.status
+    )
+
+
+def falha_de_leitura(operacao: str, exc: BaseException) -> ErroDoGoogle:
+    return ErroDoGoogle(f"Google {operacao}: a conexão falhou ({type(exc).__name__})")
+
+
+def falha_de_escrita(operacao: str, exc: BaseException) -> Exception:
+    if http.nada_saiu(exc):
+        return GoogleNaoSaiu(f"Google {operacao}: a conexão não abriu ({type(exc).__name__})")
+    return GoogleIncerto(
+        f"Google {operacao}: a conexão falhou depois do envio ({type(exc).__name__}); "
+        "a escrita pode ter chegado"
+    )

shade_plugins_google/erros.py

@@ -0,0 +1,36 @@
+"""Os erros do plugin ``google``.
+
+Separam o que **certamente não chegou** ao Google (``GoogleNaoSaiu``, um ``http.NadaSaiu``) do
+que **pode ter chegado** (``GoogleIncerto``, um ``http.ResultadoIncerto``). O token que não veio
+é o ``TokenIndisponivel`` do ``shade_sdk.plugins`` (também um ``http.NadaSaiu``).
+
+As mensagens dizem a operação, o status HTTP e o motivo que o Google dá (``PERMISSION_DENIED``,
+``insufficientPermissions``), nunca o corpo, o conteúdo da planilha nem o token.
+"""
+
+from __future__ import annotations
+
+from shade_sdk import http
+
+
+class ErroDoGoogle(Exception):
+    """A leitura não deu certo: conexão, TLS, permissão ou o Google recusou o pedido."""
+
+    def __init__(self, mensagem: str, *, status: int | None = None) -> None:
+        super().__init__(mensagem)
+        self.status = status
+
+
+class NaoEncontrado(ErroDoGoogle):
+    """A planilha, a aba ou o arquivo não existe, ou a conta conectada não o vê (404)."""
+
+
+class GoogleNaoSaiu(http.NadaSaiu):
+    """Certamente sem efeito: o Google recusou o pedido (4xx, inclusive o 429 que sobrou das
+    retentativas) ou a rede falhou antes de enviá-lo."""
+
+
+class GoogleIncerto(http.ResultadoIncerto):
+    """Pode ter tido efeito: o pedido foi enviado e a resposta não veio, veio com erro do
+    servidor (5xx) ou não se leu. Conferir antes de refazer: a linha pode ter entrado na
+    planilha, e o arquivo pode estar no Drive."""

shade_plugins_google-0.1.0.dist-info/METADATA

@@ -0,0 +1,86 @@
+Metadata-Version: 2.5
+Name: shade-plugins-google
+Version: 0.1.0
+Summary: Ler e escrever no Google Sheets e listar, baixar e enviar no Google Drive, com o token OAuth da conexão da plataforma.
+Author: ShadeOne
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: shade-sdk<0.23,>=0.22.3
+Description-Content-Type: text/markdown
+
+# shade-plugins-google
+
+Lê e escreve no Google Sheets e lista, baixa e envia arquivos no Google Drive de dentro de um robô
+do [`shade-sdk`](https://pypi.org/project/shade-sdk/). A conta Google é a conexão OAuth da
+plataforma: o robô recebe só o token de acesso, sob demanda, e nunca vê a senha nem o refresh
+token. Só a biblioteca padrão do Python: nenhuma dependência além do `shade-sdk`.
+
+No `shade.toml` do robô, os hosts das APIs vão em `[hosts] permitidos` e a conexão em `[conexoes]`:
+
+```toml
+[hosts]
+permitidos = ["sheets.googleapis.com", "www.googleapis.com"]
+
+[conexoes]
+nomes = ["google-drive"]
+
+[plugins]
+google = "0.1.0"
+```
+
+```python
+import shade_plugins_google as google
+
+# Leitura: a qualquer momento, inclusive no ensaio.
+for pedido in google.ler_planilha("1AbC...", "Pedidos!A1:D"):  # uma linha por dict
+    ...
+for arquivo in google.listar_arquivos(nome="comprovante", tipo="application/pdf"):
+    google.baixar_arquivo(arquivo["id"])  # grava em google/<nome> no diretório de trabalho
+
+# Escrita: só dentro de item.efetivar() (no ensaio não roda).
+with item.efetivar("registrar na planilha"):
+    google.escrever_linha("1AbC...", "Pedidos!A1", [item["pedido"], item["cliente"], "ok"])
+
+with item.efetivar("guardar o comprovante"):
+    google.enviar_arquivo("comprovante.pdf", pasta="1XyZ...")
+```
+
+## A conta e o escopo
+
+- Na plataforma, conecte a conta em **Conectores → Google Drive**. O robô usa a conexão de quem
+  aprovou a versão dele; no ensaio antes da aprovação, a de quem a enviou.
+- A conexão pede os escopos `spreadsheets` (qualquer planilha que a conta veja) e `drive.file`
+  (no Drive, só o que o próprio app enviou ou que a conta abriu com ele: `listar_arquivos` e
+  `baixar_arquivo` não veem o resto do Drive, e a `pasta` de `enviar_arquivo` também tem de ser
+  uma que o app vê). Uma conexão feita antes de o escopo `spreadsheets` existir precisa ser
+  refeita.
+- No laptop (`shade run`), ponha um token de acesso da sua conta em `SHADE_TOKEN_GOOGLE_DRIVE`
+  (no `.env`). O do Google costuma valer uma hora, e o laptop não renova.
+
+## O que o plugin garante
+
+- **Um envio, um arquivo:** `enviar_arquivo` marca o arquivo com uma chave derivada do item, do
+  nome da efetivação e da ordem do envio, e procura a marca antes de criar. A retentativa e uma
+  nova execução do mesmo item acham o arquivo que já subiu, em vez de criar outro, enquanto a
+  busca do Drive o enxergar: logo depois de um envio sem confirmação, a busca pode ainda não
+  vê-lo. Por isso o envio sem confirmação é `GoogleIncerto` e o item fica retido para
+  conferência.
+- **Linha sem duplicata escondida:** o Sheets não reconhece repetição, então `escrever_linha` só
+  repete o que certamente não chegou (a conexão recusada, o `429`). Se o pedido saiu e a
+  confirmação não veio, o erro é `GoogleIncerto` e o item fica retido para conferência.
+- **Texto é texto:** `escrever_linha` grava cru (`RAW`): `=HYPERLINK(...)` vira texto, nunca
+  fórmula.
+- **Token renovado pela plataforma:** o `401` troca o token uma vez e repete o pedido, que não
+  teve efeito. O `429` que sobra das retentativas é `GoogleNaoSaiu`: o Google limitou antes de
+  aplicar.
+- **Prazo:** `timeout=` (30 s) vale para a chamada inteira, retentativas incluídas. Cada chamada
+  vira um evento com a operação, o host, a duração e o status, sem conteúdo nem token.
+
+## Limites desta versão
+
+- O envio é de um pedido só, até 5 MB.
+- Arquivos nativos do Google (Docs, Planilhas, Apresentações) não se baixam; a planilha se lê com
+  `ler_planilha`.
+
+Licença Apache-2.0.

shade_plugins_google-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+shade_plugins_google/__init__.py,sha256=twhEGSK5XM6mKaHLKY_8ZDmdbfInmPJ_3Gn9LEuuLtk,21829
+shade_plugins_google/_cliente.py,sha256=G9xzskTlQgAORdqbUziJhxDmQHsoRl8P1yslrsKyF4I,11453
+shade_plugins_google/erros.py,sha256=V9yHsKkRV6PI7-c6uZ6gp-DU7p0QWP6LBVoau87LivM,1426
+shade_plugins_google-0.1.0.dist-info/METADATA,sha256=zdDVlHmRh33Rp3qEF_eCAuM6UjTteCL4T8zkT0ELzhM,3986
+shade_plugins_google-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+shade_plugins_google-0.1.0.dist-info/entry_points.txt,sha256=kLhU1O4Q9YkM8ZA4S5f5iDXFb8QcbKXMQzqPj0hR8b0,57
+shade_plugins_google-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+shade_plugins_google-0.1.0.dist-info/RECORD,,

shade_plugins_google-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

shade_plugins_google-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[shade_sdk.plugins]
+google = shade_plugins_google:PLUGIN

shade_plugins_google-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.