/rumps

Ridiculously Uncomplicated macOS Python Statusbar apps

Primary LanguagePythonBSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

rumps

Ridiculously Uncomplicated macOS Python Statusbar apps.

https://raw.github.com/jaredks/rumps/master/examples/rumps_example.png

import rumps

class AwesomeStatusBarApp(rumps.App):
    @rumps.clicked("Preferences")
    def prefs(self, _):
        rumps.alert("jk! no preferences available!")

    @rumps.clicked("Silly button")
    def onoff(self, sender):
        sender.state = not sender.state

    @rumps.clicked("Say hi")
    def sayhi(self, _):
        rumps.notification("Awesome title", "amazing subtitle", "hi!!1")

if __name__ == "__main__":
    AwesomeStatusBarApp("Awesome App").run()

How fun!?

rumps can greatly shorten the code required to generate a working app. No PyObjC underscore syntax required!

Use case

rumps is for any console-based program that would benefit from a simple configuration toolbar or launch menu.

Good for:

  • Notification-center-based app
  • Controlling daemons / launching separate programs
  • Updating simple info from web APIs on a timer

Not good for:

  • Any app that is first and foremost a GUI application

Required

  • PyObjC
  • Python 2.6+

Mac OS X 10.6 was shipped with Python 2.6 as the default version and PyObjC has been included in the default Python since Mac OS X 10.5. If you're using Mac OS X 10.6+ and the default Python that came with it, then rumps should be good to go!

Recommended

  • py2app

For creating standalone apps, just make sure to include rumps in the packages list. Most simple statusbar-based apps are just "background" apps (no icon in the dock; inability to tab to the application) so it is likely that you would want to set 'LSUIElement' to True. A basic setup.py would look like,

from setuptools import setup

APP = ['example_class.py']
DATA_FILES = []
OPTIONS = {
    'argv_emulation': True,
    'plist': {
        'LSUIElement': True,
    },
    'packages': ['rumps'],
}

setup(
    app=APP,
    data_files=DATA_FILES,
    options={'py2app': OPTIONS},
    setup_requires=['py2app'],
)

With this you can then create a standalone,

python setup.py py2app

Installation

Using pip,

pip install rumps

Or from source,

python setup.py install

Both of which will require sudo if installing in a system-wide location.

Virtual Environments

There are issues with using virtualenv because of the way the Python executable is copied. Although rumps attempts to apply a fix (hack) during the install process, it is not suggested to use virtualenv.

To ensure proper functionality, either use venv (packaged with Python 3) or create a standalone app using py2app.

python3 -m venv env

Documentation

Documentation is available at http://rumps.readthedocs.org

License

"Modified BSD License". See LICENSE for details. Copyright Jared Suttles, 2020.

Works Made With rumps

20twenty20 - eohomegrownapps

42-CanITakeCoffee - avallete

air-quality-app - grtfou

Airplane - C-Codes

allbar - raphaelhuefner

allofthelights - kenkeiter

attendee-tool-mlh - Bucknalla

Auroratain - Matt-McConway

AutoSSP - viktyz

AutoVPN - shadyabhi

BackgroundsForReddit - karlaugsten

bink - e40

bitracker - JZChen

BluetoothEvent - lostman-github

break-timer - jjmojojjmojo

breaker - amloewi

bundle-checker - jeffgodwyll

c1t1 - e9t

camsketch - pdubroy

ComicStreamer - beville

commitwatch - chrisfosterelli

computer-time - rbrich

crypto-ticker-macOS - mqulateen

cryptocoin-quotes - Sayan98

cuco - jjuanda

currency-converter - ahmedelgohary

dns.app - damln

Dokky - rogierkn

dolar_bitcoin - celis

duplicati - duplicati

earth - nickrobson

ForceNapClone - hroftgit

freelan-bar - privacee

g-assistant-mac - agucova

gapa - ozlerhakan

GitSyncApp - jachin

Gumpy - RobGraham

Habitus - kmundnic

HalfCaff - dougn

happymac - laffra

harmenubar - vekkt0r

hatarake - kfdm-archive

HipStatus - jamfit

hp-lorem - jamesrampton

hs100-status-bar - craig-davis

iBatteryStats - saket13

iBrew - Tristan79

idiot - snare

interlocking - jrauch

istat - Lingdu0

keynote_snap - sasn0

Keypad - jelmer04

keyringo - tokenizecx

kizkiz - TkTech

koinex-status-ticker - kirantambe

leaguefriend - pandarison

LifxController - mitchmcdee

lil_ip_toolbar - mchlrtkwski

mac-shrew - mejmo

MacFaceID - vkalia602

majo-v - r4lv

MBatteryApp - Elliot-Potts

McBing - bagabont

Memcode - aroraenterprise

memdam - joshalbrecht

MenuBarGmail - rcmdnk

midi2dmx - davidbistolas

monero-ticker - Cisplatin

MoodLight - kretash

MoonTicker - skxu

musicbar - russelg

narcissist - helmholtz

Noise-Line - Dnncha

nowplaying_statusbar - MataiulS

obmenka - vlakin

org-clock-dashboard - srid

osx-bamboo-plan-status - spalter

osx-myair - CameronEx

PennAppsX - yousufmsoliman

phd - ChrisCummins

pokemon-go-status - pboardman

polly - interrogator

pompy - camilopayan

project_screen_to_lifx - emiraga

PSPEWC-mac - jacquesCedric

py-Timey - asakasinsky

pymodoro - volflow

pySplash - Egregors

quick-grayscale - shubhamjain

quiet - hiroshi

Radio-Crowd - EliMendelson

RadioBar - wass3r

RadioBar (fork) - mdbraber

rescuetime_statusbar - MauriceZ

rideindegochecker - josepvalls

RitsWifi - fang2hou

safety-bar - pyupio

SAT-Vocab-Quizzer - Legoben

sb-translate - leandroltavares

sharfoo - furqan-shakoor

ShortyURLShortener - Naktrem

shotput - amussey

SingMenuData - ponyfleisch

slack-status-bar - ericwb

slackify - nikodraca

snippets - quillford

sonostus - sarkkine

Spaceapi-Desktop - UrLab

SpaceSwitcher - SankaitLaroiya

SpotifyLyrics - yask123

steemticker-osx - ZachC16

Timebox - visini

Telkom-ADSL-Data-Usage - parautenbach

Telton - Yywww

these-days - hahayes

time-tracking - willsgrigg

timerbar - uberalex

tracker - jtxx000

TrojanA - chrisxiao

umma - mankoff

upbrew - stchris

uptimeIndicator - paulaborde

urstatus - kysely

uStatus - kdungs

VagrantBar - kingsdigitallab

voiceplay - tb0hdan

volsbb - akigugale

Volumio_bar - volderette

votingpowerbar - therealwolf42

WallpDesk - L3rchal

webcronic - josselinauguste

Whale - amka

WhyFi - OzTamir

WordTime - Demonstrandum

work_time_percent_applet - Benhgift

WorkWise - 8ern4ard

xCodea - lowne

yaca - drproteus

Zero - beejhuff

Submit a pull request to add your own!