{"id":26295589,"url":"https://github.com/refrainit/zangetsu-data","last_synced_at":"2026-05-06T17:33:37.253Z","repository":{"id":282396661,"uuid":"948406469","full_name":"refrainit/zangetsu-data","owner":"refrainit","description":"PostgreSQL、BigQuery、Googleスプレッドシートへアクセスし、データを取得することをサポートするライブラリ","archived":false,"fork":false,"pushed_at":"2025-03-16T07:18:02.000Z","size":116,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-03T20:55:34.507Z","etag":null,"topics":["bigquery","pip","postgresql","python","spreadsheet","zangetsu"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/zangetsu-data/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/refrainit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-14T09:30:47.000Z","updated_at":"2025-03-16T07:18:04.000Z","dependencies_parsed_at":null,"dependency_job_id":"2553185d-24b5-4fff-8040-ac2b2bb821a9","html_url":"https://github.com/refrainit/zangetsu-data","commit_stats":null,"previous_names":["refrainit/zangetsu-data"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/refrainit/zangetsu-data","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refrainit%2Fzangetsu-data","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refrainit%2Fzangetsu-data/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refrainit%2Fzangetsu-data/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refrainit%2Fzangetsu-data/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/refrainit","download_url":"https://codeload.github.com/refrainit/zangetsu-data/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refrainit%2Fzangetsu-data/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32704404,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T08:33:17.875Z","status":"ssl_error","status_checked_at":"2026-05-06T08:33:17.221Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bigquery","pip","postgresql","python","spreadsheet","zangetsu"],"created_at":"2025-03-15T04:14:28.027Z","updated_at":"2026-05-06T17:33:37.248Z","avatar_url":"https://github.com/refrainit.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zangetsu-data\n\nデータベース接続とデータ操作のための包括的な Python ライブラリです。複数のデータベースタイプとスプレッドシートに対する統一的なインターフェースを提供します。\n\n## 特徴\n\n- **多様なデータソースサポート**：PostgreSQL、BigQuery、GoogleSpreadsheet など\n- **統一インターフェース**：すべてのデータソースで一貫したメソッド呼び出し\n- **SQL ファイルテンプレート**：Jinja2 を使用した柔軟な SQL クエリ管理\n- **Pandas 統合**：クエリ結果を直接 DataFrame として取得\n- **環境変数サポート**：設定の外部化が容易\n- **エラーハンドリング**：例外処理とロギング機能の統合\n- **スキーマ管理**：テーブル定義の簡単な取得と管理\n\n## インストール\n\n```bash\npip install zangetsu-data\n```\n\n## 基本的な使い方\n\n### データベース共通機能\n\n```python\nfrom zangetsu_data.common_database import Database\n\n# データベース接続文字列を指定して接続\ndb = Database(\"postgresql://username:password@localhost:5432/mydatabase\")\n\n# 接続確立\ndb.connect()\n\n# クエリの実行とデータの取得\ndf = db.read_sql(\"SELECT * FROM users WHERE age \u003e %s\", [18])\nprint(df)\n\n# テーブルリストの取得\ntables = db.list_tables()\nprint(tables)\n\n# リソースの解放\ndb.close()\n```\n\n### PostgreSQL データベース接続\n\n```python\nfrom zangetsu_data.postgresql import Postgresql\n\n# 接続情報を使用してインスタンス作成\ndb = Postgresql(\n    host=\"localhost\",\n    port=\"5432\",\n    db_name=\"mydb\",\n    username=\"user\",\n    password=\"pass\"\n)\n\n# SQLクエリの実行\ndf = db.read_sql(\"SELECT * FROM users\")\nprint(df)\n\n# テーブルリストの取得\ntables = db.list_tables()\nprint(tables)\n```\n\n### Google BigQuery 接続\n\n```python\nfrom zangetsu_data.bigquery import BigQuery\n\n# サービスアカウントキーファイルを使用して接続\nbq = BigQuery(\n    project_id=\"my-project\",\n    dataset_id=\"my_dataset\",\n    credentials_path=\"/path/to/service-account-key.json\"\n)\n\n# クエリの実行\ndf = bq.read_sql(\"SELECT * FROM `my_dataset.my_table` LIMIT 1000\")\nprint(df)\n\n# データベース情報の確認\ninfo = bq.show_database_info()\nprint(info)\n```\n\n### Google スプレッドシート操作\n\n```python\nfrom zangetsu_data.spreadsheet import GoogleSpreadsheet\n\n# サービスアカウントキーファイルを使用して接続\ngs = GoogleSpreadsheet(\n    credentials_path=\"/path/to/service-account-key.json\",\n    spreadsheet_id=\"your_spreadsheet_id\"\n)\n\n# シートからデータを読み込み\ndf = gs.read_sheet(\"Sheet1\", \"A1:D10\")\nprint(df)\n\n# DataFrameデータをシートに書き込み\nimport pandas as pd\ndata_df = pd.DataFrame({\"Name\": [\"Alice\", \"Bob\"], \"Score\": [85, 92]})\ngs.write_sheet(data_df, \"Sheet1\", \"A1\", include_header=True)\n\n# データをシートに追加\nnew_data_df = pd.DataFrame({\"Name\": [\"Charlie\"], \"Score\": [78]})\ngs.append_sheet(new_data_df, \"Sheet1\")\n\n# スプレッドシート内のシート一覧取得\nsheets = gs.get_sheet_names()\nprint(sheets)\n```\n\n## SQL テンプレート機能\n\nSQL クエリをファイルとして管理し、テンプレート変数で動的に生成できます。\n\n### ディレクトリ構成\n\n```\nyour_project/\n  ├── app.py\n  └── sql/\n      ├── users_by_age.sql\n      └── orders_summary.sql\n```\n\n### SQL ファイル例 (sql/users_by_age.sql)\n\n```sql\nSELECT\n  id,\n  name,\n  email,\n  age\nFROM\n  users\nWHERE\n  age BETWEEN {{ min_age }} AND {{ max_age }}\n  {% if status %}\n  AND status = '{{ status }}'\n  {% endif %}\n```\n\n### Python コードでの利用\n\n```python\nfrom zangetsu_data.common_database import Database\n\ndb = Database(\"postgresql://username:password@localhost:5432/mydatabase\", sql_dir=\"sql\")\n\n# SQLファイルを読み込み、変数を適用してクエリを取得\nsql = db.get_query_from_file(\"users_by_age\", min_age=18, max_age=30, status=\"active\")\nprint(sql)\n\n# SQLファイルを使用して直接クエリを実行\ndf = db.execute_query_file(\n    \"users_by_age\",\n    {\"department\": \"sales\"},  # SQLのプレースホルダに渡すパラメータ\n    min_age=20,  # テンプレート変数\n    max_age=40\n)\nprint(df)\n```\n\n## データベーススキーマ管理\n\n```python\nfrom zangetsu_data.postgresql import Postgresql\n\ndb = Postgresql(\n    host=\"localhost\",\n    port=\"5432\",\n    db_name=\"mydb\",\n    username=\"user\",\n    password=\"pass\"\n)\n\n# 特定のテーブルのスキーマ取得\nusers_schema = db.get_table_schema(\"users\")\nprint(users_schema)\n\n# データベース内の全テーブルのスキーマ取得\nall_schemas = db.get_tables_schema()\nprint(all_schemas)\n\n# スキーマのDataFrame形式での出力\nschema_df = db.export_schema_to_dataframe(\"users\")\nprint(schema_df)\n```\n\n## 環境変数\n\n`/.env`ファイルを使用して設定を外部化できます:\n\n```\n# BigQuery Configuration\nGOOGLE_APPLICATION_CREDENTIALS=/path/to/your/service-account.json\n```\n\n## テーブル操作\n\n```python\nfrom zangetsu_data.common_database import Database\n\ndb = Database(\"postgresql://username:password@localhost:5432/mydatabase\")\n\n# 新しいテーブルの作成\ndb.create_table(\n    \"employees\",\n    {\n        \"id\": \"SERIAL PRIMARY KEY\",\n        \"name\": \"VARCHAR(255) NOT NULL\",\n        \"email\": \"VARCHAR(255) UNIQUE\",\n        \"department\": \"VARCHAR(100)\",\n        \"hire_date\": \"DATE\"\n    }\n)\n\n# テーブルの削除\ndb.delete_table(\"old_employees\")\n\n# トランザクション内での複数クエリの実行\ndb.transaction_query([\n    \"INSERT INTO logs (message) VALUES ('Operation started')\",\n    \"UPDATE status SET current = 'processing'\",\n    \"INSERT INTO logs (message) VALUES ('Status updated')\"\n])\n```\n\n## 貢献\n\n1. リポジトリをフォーク\n2. 機能ブランチを作成 (`git checkout -b feature/amazing-feature`)\n3. 変更をコミット (`git commit -m 'Add some amazing feature'`)\n4. ブランチをプッシュ (`git push origin feature/amazing-feature`)\n5. プルリクエストを作成\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frefrainit%2Fzangetsu-data","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frefrainit%2Fzangetsu-data","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frefrainit%2Fzangetsu-data/lists"}