{"id":13610382,"url":"https://github.com/boppreh/mouse","last_synced_at":"2025-05-15T03:07:26.622Z","repository":{"id":43217811,"uuid":"99284907","full_name":"boppreh/mouse","owner":"boppreh","description":" Hook and simulate global mouse events in pure Python","archived":false,"fork":false,"pushed_at":"2024-07-09T15:35:54.000Z","size":40,"stargazers_count":928,"open_issues_count":95,"forks_count":138,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-04-14T03:07:04.120Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/boppreh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","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,"zenodo":null}},"created_at":"2017-08-04T00:03:33.000Z","updated_at":"2025-04-11T22:49:54.000Z","dependencies_parsed_at":"2025-04-14T01:09:08.157Z","dependency_job_id":"28668fde-17fa-45e0-8bbc-883d1b0cedce","html_url":"https://github.com/boppreh/mouse","commit_stats":{"total_commits":38,"total_committers":9,"mean_commits":4.222222222222222,"dds":0.3157894736842105,"last_synced_commit":"7b773393ed58824b1adf055963a2f9e379f52cc3"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boppreh%2Fmouse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boppreh%2Fmouse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boppreh%2Fmouse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boppreh%2Fmouse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/boppreh","download_url":"https://codeload.github.com/boppreh/mouse/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254264766,"owners_count":22041793,"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":[],"created_at":"2024-08-01T19:01:44.178Z","updated_at":"2025-05-15T03:07:21.613Z","avatar_url":"https://github.com/boppreh.png","language":"Python","readme":"\nmouse\n=====\n\nTake full control of your mouse with this small Python library. Hook global events, register hotkeys, simulate mouse movement and clicks, and much more.\n\n_Huge thanks to [Kirill Pavlov](http://kirillpavlov.com/) for donating the package name. If you are looking for the Cheddargetter.com client implementation, [`pip install mouse==0.5.0`](https://pypi.python.org/pypi/mouse/0.5.0)._\n\n## Features\n\n- Global event hook on all mice devices (captures events regardless of focus).\n- **Listen** and **sends** mouse events.\n- Works with **Windows** and **Linux** (requires sudo).\n- Works with **MacOS** (requires granting accessibility permissions to terminal/python in System Preferences -\u003e Security \\\u0026 Privacy)\n- **Pure Python**, no C modules to be compiled.\n- **Zero dependencies** on Windows and Linux. Trivial to install and deploy, just copy the files.\n- **Python 2 and 3**.\n- Includes **high level API** (e.g. [record](#mouse.record) and [play](#mouse.play).\n- Events automatically captured in separate thread, doesn't block main program.\n- Tested and documented.\n\nThis program makes no attempt to hide itself, so don't use it for keyloggers.\n\n## Usage\n\nInstall the [PyPI package](https://pypi.python.org/pypi/mouse/):\n\n    $ sudo pip install mouse\n\nor clone the repository (no installation required, source files are sufficient):\n\n    $ git clone https://github.com/boppreh/mouse\n\nThen check the [API docs](https://github.com/boppreh/mouse#api) to see what features are available.\n\n\n## Known limitations:\n\n- Events generated under Windows don't report device id (`event.device == None`). [#21](https://github.com/boppreh/keyboard/issues/21)\n- To avoid depending on X the Linux parts reads raw device files (`/dev/input/input*`) but this requires root.\n- Other applications, such as some games, may register hooks that swallow all key events. In this case `mouse` will be unable to report events.\n\n\n\n# API\n#### Table of Contents\n\n- [mouse.**ButtonEvent**](#mouse.ButtonEvent)\n- [mouse.**DOUBLE**](#mouse.DOUBLE)\n- [mouse.**DOWN**](#mouse.DOWN)\n- [mouse.**LEFT**](#mouse.LEFT)\n- [mouse.**MIDDLE**](#mouse.MIDDLE)\n- [mouse.**MoveEvent**](#mouse.MoveEvent)\n- [mouse.**RIGHT**](#mouse.RIGHT)\n- [mouse.**UP**](#mouse.UP)\n- [mouse.**WheelEvent**](#mouse.WheelEvent)\n- [mouse.**X**](#mouse.X)\n- [mouse.**X2**](#mouse.X2)\n- [mouse.**version**](#mouse.version)\n- [mouse.**is\\_pressed**](#mouse.is_pressed)\n- [mouse.**press**](#mouse.press) *(aliases: `hold`)*\n- [mouse.**release**](#mouse.release)\n- [mouse.**click**](#mouse.click)\n- [mouse.**double\\_click**](#mouse.double_click)\n- [mouse.**right\\_click**](#mouse.right_click)\n- [mouse.**wheel**](#mouse.wheel)\n- [mouse.**move**](#mouse.move)\n- [mouse.**drag**](#mouse.drag)\n- [mouse.**on\\_button**](#mouse.on_button)\n- [mouse.**on\\_click**](#mouse.on_click)\n- [mouse.**on\\_double\\_click**](#mouse.on_double_click)\n- [mouse.**on\\_right\\_click**](#mouse.on_right_click)\n- [mouse.**on\\_middle\\_click**](#mouse.on_middle_click)\n- [mouse.**wait**](#mouse.wait)\n- [mouse.**get\\_position**](#mouse.get_position)\n- [mouse.**hook**](#mouse.hook)\n- [mouse.**unhook**](#mouse.unhook)\n- [mouse.**unhook\\_all**](#mouse.unhook_all)\n- [mouse.**record**](#mouse.record)\n- [mouse.**play**](#mouse.play) *(aliases: `replay`)*\n\n\n\u003ca name=\"mouse.ButtonEvent\"/\u003e\n\n## class mouse.**ButtonEvent**\n\nButtonEvent(event_type, button, time)\n\n\n\u003ca name=\"ButtonEvent.button\"/\u003e\n\n### ButtonEvent.**button**\n\nAlias for field number 1\n\n\n\u003ca name=\"ButtonEvent.count\"/\u003e\n\n### ButtonEvent.**count**(self, value, /)\n\nReturn number of occurrences of value.\n\n\n\u003ca name=\"ButtonEvent.event_type\"/\u003e\n\n### ButtonEvent.**event\\_type**\n\nAlias for field number 0\n\n\n\u003ca name=\"ButtonEvent.index\"/\u003e\n\n### ButtonEvent.**index**(self, value, start=0, stop=9223372036854775807, /)\n\nReturn first index of value.\n\nRaises ValueError if the value is not present.\n\n\n\u003ca name=\"ButtonEvent.time\"/\u003e\n\n### ButtonEvent.**time**\n\nAlias for field number 2\n\n\n\n\n\u003ca name=\"mouse.DOUBLE\"/\u003e\n\n## mouse.**DOUBLE**\n```py\n= 'double'\n```\n\n\u003ca name=\"mouse.DOWN\"/\u003e\n\n## mouse.**DOWN**\n```py\n= 'down'\n```\n\n\u003ca name=\"mouse.LEFT\"/\u003e\n\n## mouse.**LEFT**\n```py\n= 'left'\n```\n\n\u003ca name=\"mouse.MIDDLE\"/\u003e\n\n## mouse.**MIDDLE**\n```py\n= 'middle'\n```\n\n\u003ca name=\"mouse.MoveEvent\"/\u003e\n\n## class mouse.**MoveEvent**\n\nMoveEvent(x, y, time)\n\n\n\u003ca name=\"MoveEvent.count\"/\u003e\n\n### MoveEvent.**count**(self, value, /)\n\nReturn number of occurrences of value.\n\n\n\u003ca name=\"MoveEvent.index\"/\u003e\n\n### MoveEvent.**index**(self, value, start=0, stop=9223372036854775807, /)\n\nReturn first index of value.\n\nRaises ValueError if the value is not present.\n\n\n\u003ca name=\"MoveEvent.time\"/\u003e\n\n### MoveEvent.**time**\n\nAlias for field number 2\n\n\n\u003ca name=\"MoveEvent.x\"/\u003e\n\n### MoveEvent.**x**\n\nAlias for field number 0\n\n\n\u003ca name=\"MoveEvent.y\"/\u003e\n\n### MoveEvent.**y**\n\nAlias for field number 1\n\n\n\n\n\u003ca name=\"mouse.RIGHT\"/\u003e\n\n## mouse.**RIGHT**\n```py\n= 'right'\n```\n\n\u003ca name=\"mouse.UP\"/\u003e\n\n## mouse.**UP**\n```py\n= 'up'\n```\n\n\u003ca name=\"mouse.WheelEvent\"/\u003e\n\n## class mouse.**WheelEvent**\n\nWheelEvent(delta, time)\n\n\n\u003ca name=\"WheelEvent.count\"/\u003e\n\n### WheelEvent.**count**(self, value, /)\n\nReturn number of occurrences of value.\n\n\n\u003ca name=\"WheelEvent.delta\"/\u003e\n\n### WheelEvent.**delta**\n\nAlias for field number 0\n\n\n\u003ca name=\"WheelEvent.index\"/\u003e\n\n### WheelEvent.**index**(self, value, start=0, stop=9223372036854775807, /)\n\nReturn first index of value.\n\nRaises ValueError if the value is not present.\n\n\n\u003ca name=\"WheelEvent.time\"/\u003e\n\n### WheelEvent.**time**\n\nAlias for field number 1\n\n\n\n\n\u003ca name=\"mouse.X\"/\u003e\n\n## mouse.**X**\n```py\n= 'x'\n```\n\n\u003ca name=\"mouse.X2\"/\u003e\n\n## mouse.**X2**\n```py\n= 'x2'\n```\n\n\u003ca name=\"mouse.version\"/\u003e\n\n## mouse.**version**\n```py\n= '0.7.1'\n```\n\n\u003ca name=\"mouse.is_pressed\"/\u003e\n\n## mouse.**is\\_pressed**(button=\u0026#x27;left\u0026#x27;)\n\n[\\[source\\]](https://github.com/boppreh/mouse/blob/master/mouse/__init__.py#L78)\n\nReturns True if the given button is currently pressed.\n\n\n\u003ca name=\"mouse.press\"/\u003e\n\n## mouse.**press**(button=\u0026#x27;left\u0026#x27;)\n\n[\\[source\\]](https://github.com/boppreh/mouse/blob/master/mouse/__init__.py#L83)\n\nPresses the given button (but doesn't release).\n\n\n\u003ca name=\"mouse.release\"/\u003e\n\n## mouse.**release**(button=\u0026#x27;left\u0026#x27;)\n\n[\\[source\\]](https://github.com/boppreh/mouse/blob/master/mouse/__init__.py#L87)\n\nReleases the given button.\n\n\n\u003ca name=\"mouse.click\"/\u003e\n\n## mouse.**click**(button=\u0026#x27;left\u0026#x27;)\n\n[\\[source\\]](https://github.com/boppreh/mouse/blob/master/mouse/__init__.py#L91)\n\nSends a click with the given button.\n\n\n\u003ca name=\"mouse.double_click\"/\u003e\n\n## mouse.**double\\_click**(button=\u0026#x27;left\u0026#x27;)\n\n[\\[source\\]](https://github.com/boppreh/mouse/blob/master/mouse/__init__.py#L96)\n\nSends a double click with the given button.\n\n\n\u003ca name=\"mouse.right_click\"/\u003e\n\n## mouse.**right\\_click**()\n\n[\\[source\\]](https://github.com/boppreh/mouse/blob/master/mouse/__init__.py#L101)\n\nSends a right click with the given button.\n\n\n\u003ca name=\"mouse.wheel\"/\u003e\n\n## mouse.**wheel**(delta=1)\n\n[\\[source\\]](https://github.com/boppreh/mouse/blob/master/mouse/__init__.py#L105)\n\nScrolls the wheel `delta` clicks. Sign indicates direction.\n\n\n\u003ca name=\"mouse.move\"/\u003e\n\n## mouse.**move**(x, y, absolute=True, duration=0, steps_per_second=120.0)\n\n[\\[source\\]](https://github.com/boppreh/mouse/blob/master/mouse/__init__.py#L109)\n\n\nMoves the mouse. If `absolute`, to position (x, y), otherwise move relative\nto the current position. If `duration` is non-zero, animates the movement.\nThe fps of the animation is determined by 'steps_per_second', default is 120.\n\n\n\u003ca name=\"mouse.drag\"/\u003e\n\n## mouse.**drag**(start\\_x, start\\_y, end\\_x, end\\_y, absolute=True, duration=0)\n\n[\\[source\\]](https://github.com/boppreh/mouse/blob/master/mouse/__init__.py#L143)\n\n\nHolds the left mouse button, moving from start to end position, then\nreleases. `absolute` and `duration` are parameters regarding the mouse\nmovement.\n\n\n\n\u003ca name=\"mouse.on_button\"/\u003e\n\n## mouse.**on\\_button**(callback, args=(), buttons=(\u0026#x27;left\u0026#x27;, \u0026#x27;middle\u0026#x27;, \u0026#x27;right\u0026#x27;, \u0026#x27;x\u0026#x27;, \u0026#x27;x2\u0026#x27;), types=(\u0026#x27;up\u0026#x27;, \u0026#x27;down\u0026#x27;, \u0026#x27;double\u0026#x27;))\n\n[\\[source\\]](https://github.com/boppreh/mouse/blob/master/mouse/__init__.py#L156)\n\nInvokes `callback` with `args` when the specified event happens.\n\n\n\u003ca name=\"mouse.on_click\"/\u003e\n\n## mouse.**on\\_click**(callback, args=())\n\n[\\[source\\]](https://github.com/boppreh/mouse/blob/master/mouse/__init__.py#L170)\n\nInvokes `callback` with `args` when the left button is clicked.\n\n\n\u003ca name=\"mouse.on_double_click\"/\u003e\n\n## mouse.**on\\_double\\_click**(callback, args=())\n\n[\\[source\\]](https://github.com/boppreh/mouse/blob/master/mouse/__init__.py#L174)\n\n\nInvokes `callback` with `args` when the left button is double clicked.\n\n\n\n\u003ca name=\"mouse.on_right_click\"/\u003e\n\n## mouse.**on\\_right\\_click**(callback, args=())\n\n[\\[source\\]](https://github.com/boppreh/mouse/blob/master/mouse/__init__.py#L180)\n\nInvokes `callback` with `args` when the right button is clicked.\n\n\n\u003ca name=\"mouse.on_middle_click\"/\u003e\n\n## mouse.**on\\_middle\\_click**(callback, args=())\n\n[\\[source\\]](https://github.com/boppreh/mouse/blob/master/mouse/__init__.py#L184)\n\nInvokes `callback` with `args` when the middle button is clicked.\n\n\n\u003ca name=\"mouse.wait\"/\u003e\n\n## mouse.**wait**(button=\u0026#x27;left\u0026#x27;, target\\_types=(\u0026#x27;up\u0026#x27;, \u0026#x27;down\u0026#x27;, \u0026#x27;double\u0026#x27;))\n\n[\\[source\\]](https://github.com/boppreh/mouse/blob/master/mouse/__init__.py#L188)\n\n\nBlocks program execution until the given button performs an event.\n\n\n\n\u003ca name=\"mouse.get_position\"/\u003e\n\n## mouse.**get\\_position**()\n\n[\\[source\\]](https://github.com/boppreh/mouse/blob/master/mouse/__init__.py#L199)\n\nReturns the (x, y) mouse position.\n\n\n\u003ca name=\"mouse.hook\"/\u003e\n\n## mouse.**hook**(callback)\n\n[\\[source\\]](https://github.com/boppreh/mouse/blob/master/mouse/__init__.py#L203)\n\n\nInstalls a global listener on all available mouses, invoking `callback`\neach time it is moved, a key status changes or the wheel is spun. A mouse\nevent is passed as argument, with type either `mouse.ButtonEvent`,\n`mouse.WheelEvent` or `mouse.MoveEvent`.\n\nReturns the given callback for easier development.\n\n\n\n\u003ca name=\"mouse.unhook\"/\u003e\n\n## mouse.**unhook**(callback)\n\n[\\[source\\]](https://github.com/boppreh/mouse/blob/master/mouse/__init__.py#L215)\n\n\nRemoves a previously installed hook.\n\n\n\n\u003ca name=\"mouse.unhook_all\"/\u003e\n\n## mouse.**unhook\\_all**()\n\n[\\[source\\]](https://github.com/boppreh/mouse/blob/master/mouse/__init__.py#L221)\n\n\nRemoves all hooks registered by this application. Note this may include\nhooks installed by high level functions, such as [`record`](#mouse.record).\n\n\n\n\u003ca name=\"mouse.record\"/\u003e\n\n## mouse.**record**(button=\u0026#x27;right\u0026#x27;, target\\_types=(\u0026#x27;down\u0026#x27;,))\n\n[\\[source\\]](https://github.com/boppreh/mouse/blob/master/mouse/__init__.py#L228)\n\n\nRecords all mouse events until the user presses the given button.\nThen returns the list of events recorded. Pairs well with [`play(events)`](#mouse.play).\n\nNote: this is a blocking function.\nNote: for more details on the mouse hook and events see [`hook`](#mouse.hook).\n\n\n\n\u003ca name=\"mouse.play\"/\u003e\n\n## mouse.**play**(events, speed\\_factor=1.0, include\\_clicks=True, include\\_moves=True, include\\_wheel=True)\n\n[\\[source\\]](https://github.com/boppreh/mouse/blob/master/mouse/__init__.py#L242)\n\n\nPlays a sequence of recorded events, maintaining the relative time\nintervals. If speed_factor is \u003c= 0 then the actions are replayed as fast\nas the OS allows. Pairs well with [`record()`](#mouse.record).\n\nThe parameters `include_*` define if events of that type should be included\nin the replay or ignored.\n","funding_links":[],"categories":["Hardware","硬件","Hardware [🔝](#readme)","资源列表","Awesome Python"],"sub_categories":["硬件","Hardware"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboppreh%2Fmouse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fboppreh%2Fmouse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboppreh%2Fmouse/lists"}