{"id":13595040,"url":"https://github.com/romis2012/python-socks","last_synced_at":"2025-05-15T13:08:56.915Z","repository":{"id":39913092,"uuid":"297057488","full_name":"romis2012/python-socks","owner":"romis2012","description":"Core proxy client (SOCKS4, SOCKS5, HTTP) functionality for Python","archived":false,"fork":false,"pushed_at":"2025-02-01T18:13:44.000Z","size":1510,"stargazers_count":105,"open_issues_count":0,"forks_count":20,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-15T03:52:37.311Z","etag":null,"topics":["anyio","asyncio","curio","http","proxy","python","socks","socks4","socks5","trio"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/romis2012.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-20T11:04:17.000Z","updated_at":"2025-03-07T12:47:13.000Z","dependencies_parsed_at":"2024-04-22T09:30:07.935Z","dependency_job_id":"3022c6c9-4a29-45dc-a325-43f7b78006cd","html_url":"https://github.com/romis2012/python-socks","commit_stats":{"total_commits":108,"total_committers":5,"mean_commits":21.6,"dds":0.03703703703703709,"last_synced_commit":"313dff94482be24bf590becc6c200553b5e50266"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/romis2012%2Fpython-socks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/romis2012%2Fpython-socks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/romis2012%2Fpython-socks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/romis2012%2Fpython-socks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/romis2012","download_url":"https://codeload.github.com/romis2012/python-socks/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254346625,"owners_count":22055808,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["anyio","asyncio","curio","http","proxy","python","socks","socks4","socks5","trio"],"created_at":"2024-08-01T16:01:42.863Z","updated_at":"2025-05-15T13:08:51.866Z","avatar_url":"https://github.com/romis2012.png","language":"Python","readme":"## python-socks\n\n[![CI](https://github.com/romis2012/python-socks/actions/workflows/ci.yml/badge.svg)](https://github.com/romis2012/python-socks/actions/workflows/ci.yml)\n[![Coverage Status](https://codecov.io/gh/romis2012/python-socks/branch/master/graph/badge.svg)](https://codecov.io/gh/romis2012/python-socks)\n[![PyPI version](https://badge.fury.io/py/python-socks.svg)](https://pypi.python.org/pypi/python-socks)\n\u003c!--\n[![Downloads](https://pepy.tech/badge/python-socks/month)](https://pepy.tech/project/python-socks)\n--\u003e\n\nThe `python-socks` package provides a core proxy client functionality for Python.\nSupports `SOCKS4(a)`, `SOCKS5(h)`, `HTTP CONNECT` proxy and provides sync and async (asyncio, trio, curio, anyio) APIs.\nYou probably don't need to use `python-socks` directly. \nIt is used internally by \n[aiohttp-socks](https://github.com/romis2012/aiohttp-socks) and [httpx-socks](https://github.com/romis2012/httpx-socks) packages.  \n\n## Requirements\n- Python \u003e= 3.8\n- async-timeout \u003e= 4.0 (optional)\n- trio \u003e= 0.24 (optional)\n- curio \u003e= 1.4 (optional)\n- anyio \u003e= 3.3.4 (optional)\n\n## Installation\n\nonly sync proxy support:\n```\npip install python-socks\n```\n\nto include optional asyncio support:\n```\npip install python-socks[asyncio]\n```\n\nto include optional trio support:\n```\npip install python-socks[trio]\n```\n\nto include optional curio support:\n```\npip install python-socks[curio]\n```\n\nto include optional anyio support:\n```\npip install python-socks[anyio]\n```\n\n## Simple usage\nWe are making secure HTTP GET request via SOCKS5 proxy\n \n#### Sync\n```python\nimport ssl\nfrom python_socks.sync import Proxy\n\nproxy = Proxy.from_url('socks5://user:password@127.0.0.1:1080')\n\n# `connect` returns standard Python socket in blocking mode\nsock = proxy.connect(dest_host='check-host.net', dest_port=443)\n\nsock = ssl.create_default_context().wrap_socket(\n    sock=sock,\n    server_hostname='check-host.net'\n)\n\nrequest = (\n    b'GET /ip HTTP/1.1\\r\\n'\n    b'Host: check-host.net\\r\\n'\n    b'Connection: close\\r\\n\\r\\n'\n)\nsock.sendall(request)\nresponse = sock.recv(4096)\nprint(response)\n```\n\n#### Async (asyncio)\n```python\nimport ssl\nimport asyncio\nfrom python_socks.async_.asyncio import Proxy\n\nproxy = Proxy.from_url('socks5://user:password@127.0.0.1:1080')\n\n# `connect` returns standard Python socket in non-blocking mode \n# so we can pass it to asyncio.open_connection(...)\nsock = await proxy.connect(dest_host='check-host.net', dest_port=443)\n\nreader, writer = await asyncio.open_connection(\n    host=None,\n    port=None,\n    sock=sock,\n    ssl=ssl.create_default_context(),\n    server_hostname='check-host.net',\n)\n\nrequest = (\n    b'GET /ip HTTP/1.1\\r\\n'\n    b'Host: check-host.net\\r\\n'\n    b'Connection: close\\r\\n\\r\\n'\n)\n\nwriter.write(request)\nresponse = await reader.read(-1)\nprint(response)\n```\n\n#### Async (trio)\n```python\nimport ssl\nimport trio\nfrom python_socks.async_.trio import Proxy\n\nproxy = Proxy.from_url('socks5://user:password@127.0.0.1:1080')\n\n# `connect` returns trio socket \n# so we can pass it to trio.SocketStream\nsock = await proxy.connect(dest_host='check-host.net', dest_port=443)\n\nstream = trio.SocketStream(sock)\n\nstream = trio.SSLStream(\n    stream, ssl.create_default_context(),\n    server_hostname='check-host.net'\n)\nawait stream.do_handshake()\n\nrequest = (\n    b'GET /ip HTTP/1.1\\r\\n'\n    b'Host: check-host.net\\r\\n'\n    b'Connection: close\\r\\n\\r\\n'\n)\n\nawait stream.send_all(request)\nresponse = await stream.receive_some(4096)\nprint(response)\n```\n\n#### Async (curio)\n```python\nimport curio.ssl as curiossl\nfrom python_socks.async_.curio import Proxy\n\nproxy = Proxy.from_url('socks5://user:password@127.0.0.1:1080')\n# `connect` returns curio.io.Socket\nsock = await proxy.connect(\n    dest_host='check-host.net',\n    dest_port=443\n)\n\nrequest = (\n    b'GET /ip HTTP/1.1\\r\\n'\n    b'Host: check-host.net\\r\\n'\n    b'Connection: close\\r\\n\\r\\n'\n)\n\nssl_context = curiossl.create_default_context()\nsock = await ssl_context.wrap_socket(\n    sock, do_handshake_on_connect=False, server_hostname='check-host.net'\n)\n\nawait sock.do_handshake()\n\nstream = sock.as_stream()\n\nawait stream.write(request)\nresponse = await stream.read(1024)\nprint(response)\n```\n\n#### Async (anyio)\n```python\nimport ssl\nfrom python_socks.async_.anyio import Proxy\n\nproxy = Proxy.from_url('socks5://user:password@127.0.0.1:1080')\n\n# `connect` returns AnyioSocketStream\nstream = await proxy.connect(\n    dest_host='check-host.net',\n    dest_port=443,\n    dest_ssl=ssl.create_default_context(),\n)\n\nrequest = (\n    b'GET /ip HTTP/1.1\\r\\n'\n    b'Host: check-host.net\\r\\n'\n    b'Connection: close\\r\\n\\r\\n'\n)\n\nawait stream.write_all(request)\nresponse = await stream.read()\nprint(response)\n```\n\n## More complex example\n\n#### A urllib3 PoolManager that routes connections via the proxy\n\n```python\nfrom urllib3 import PoolManager, HTTPConnectionPool, HTTPSConnectionPool\nfrom urllib3.connection import HTTPConnection, HTTPSConnection\nfrom python_socks.sync import Proxy\n\n\nclass ProxyHTTPConnection(HTTPConnection):\n    def __init__(self, *args, **kwargs):\n        socks_options = kwargs.pop('_socks_options')\n        self._proxy_url = socks_options['proxy_url']\n        super().__init__(*args, **kwargs)\n\n    def _new_conn(self):\n        proxy = Proxy.from_url(self._proxy_url)\n        return proxy.connect(\n            dest_host=self.host,\n            dest_port=self.port,\n            timeout=self.timeout\n        )\n\n\nclass ProxyHTTPSConnection(ProxyHTTPConnection, HTTPSConnection):\n    pass\n\n\nclass ProxyHTTPConnectionPool(HTTPConnectionPool):\n    ConnectionCls = ProxyHTTPConnection\n\n\nclass ProxyHTTPSConnectionPool(HTTPSConnectionPool):\n    ConnectionCls = ProxyHTTPSConnection\n\n\nclass ProxyPoolManager(PoolManager):\n    def __init__(self, proxy_url, timeout=5, num_pools=10, headers=None,\n                 **connection_pool_kw):\n\n        connection_pool_kw['_socks_options'] = {'proxy_url': proxy_url}\n        connection_pool_kw['timeout'] = timeout\n\n        super().__init__(num_pools, headers, **connection_pool_kw)\n\n        self.pool_classes_by_scheme = {\n            'http': ProxyHTTPConnectionPool,\n            'https': ProxyHTTPSConnectionPool,\n        }\n\n\n### and how to use it\nmanager = ProxyPoolManager('socks5://user:password@127.0.0.1:1080')\nresponse = manager.request('GET', 'https://check-host.net/ip')\nprint(response.data)\n```\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fromis2012%2Fpython-socks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fromis2012%2Fpython-socks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fromis2012%2Fpython-socks/lists"}