{"id":31045145,"url":"https://github.com/dativebase/dativetop","last_synced_at":"2025-09-14T16:58:19.088Z","repository":{"id":15818832,"uuid":"72237382","full_name":"dativebase/dativetop","owner":"dativebase","description":"DativeTop: DativeBase as a desktop application","archived":false,"fork":false,"pushed_at":"2023-03-03T20:02:21.000Z","size":1020,"stargazers_count":1,"open_issues_count":5,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-14T13:15:29.750Z","etag":null,"topics":["desktop-app","linguistics"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dativebase.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-10-28T19:48:50.000Z","updated_at":"2021-09-06T20:09:01.000Z","dependencies_parsed_at":"2023-01-11T20:24:01.828Z","dependency_job_id":null,"html_url":"https://github.com/dativebase/dativetop","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dativebase/dativetop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dativebase%2Fdativetop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dativebase%2Fdativetop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dativebase%2Fdativetop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dativebase%2Fdativetop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dativebase","download_url":"https://codeload.github.com/dativebase/dativetop/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dativebase%2Fdativetop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275136757,"owners_count":25411709,"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","status":"online","status_checked_at":"2025-09-14T02:00:10.474Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["desktop-app","linguistics"],"created_at":"2025-09-14T16:58:15.000Z","updated_at":"2025-09-14T16:58:19.062Z","avatar_url":"https://github.com/dativebase.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"================================================================================\n  DativeTop: `DativeBase`_ as a Desktop Application\n================================================================================\n\n`DativeBase`_ is *web-based* software for linguistic fieldwork. DativeTop is\nDativeBase as a *desktop* application. It is `Dative`_ and the `OLD`_ wrapped\nin a `Toga`_ and packaged into a `Briefcase`_.\n\nDativeTop is currently a work in progress. When complete, DativeTop will be a\ncross-platform (Windows and Mac OS) desktop application that allows users to\nhave local copies of their Online Linguistic Databases (OLDs). The files of\nthese OLDs will be saved to the local filesystem and their structured data will\nbe saved to local SQLite files. DativeTop provides a graphical interface to\nallow users to create new local OLDs and configure them to be read-only replicas\nof remote \"parent\" OLDs. In phase 2, DativeTop will allow the local OLDs to be\nmutable and will support synchronization and conflict resolution between local\nand remote OLDs.\n\n\nInstall\n================================================================================\n\nEnd users will ultimately be able to install DativeTop in a way that is familiar\non their platform. For example, Mac OS users will be able to download a\nDativeTop.dmg package, double-click it, drag the DativeTop.app folder to their\nApplications folder, and double-click DativeTop.app to start a running DativeTop\nthat just works.\n\nHowever, DativeTop is not there yet. In the meantime, if you are feeling\nadventurous, you can try to install DativeTop's dependencies and either run it\nin development mode or build the native binaries yourself using the\ninstructions in the sections that follow.\n\n\nInstall from Source\n================================================================================\n\nThe following instructions should install DativeTop on Unix-based systems, i.e.,\nMac OS or Linux.\n\nActivate a Python 3 virtual environment (creating it first with ``python -m\nvenv venv`` if needed)::\n\n    $ source venv/bin/activate\n\nMaking sure you are in the directory containing this file, clone the Dative and\nOLD submodules using the following git command::\n\n    $ git submodule update --init --recursive\n\nExtract the pre-built Dative (JavaScript) source to ``src/dative/dist/``::\n\n    $ rm -rf src/dative/dist/\n    $ cd src/dative/releases/\n    $ tar -zxvf release-315b7d9a8e2106612639caf13189eb2de8586278.tar.gz\n    $ cp -r dist ./../\n    $ cd ../..\n\nInstall DativeTop's (i.e., the Toga/Briefcase app's) Python dependencies::\n\n    $ pip install -r requirements.txt\n\nInstall the OLD's requirements and the OLD itself in development mode::\n\n    $ pip install -r src/old/requirements/testsqlite.txt\n    $ pip install -e src/old/\n\nInstall DativeTop Server's Python dependencies::\n\n    $ pip install -e src/dativetop/server/\n\nCreate a fresh SQLite db for DativeTop Server::\n\n    $ make refresh-dtserver\n\nBuild the DativeTop GUI. If successful, the DTGUI re-frame (ClojureScript) app\nwill be built under src/dativetop/gui/target/.::\n\n    $ cd src/dativetop/gui\n    $ npm install -g shadow-cljs\n    $ yarn\n    $ make build\n    $ cd ../../..\n\nAt this point, if all of the above was successful, you should be able to start\nDativeTop in development mode with the following::\n\n    $ briefcase dev\n\nFor details on how to use DativeTop, see the :ref:`Using DativeTop` section.\n\n\nInstall on Windows\n--------------------------------------------------------------------------------\n\nInstallation on Windows is similar to that on Mac (Unix). First, install Git and\nPython 3.6 using the pre-built installers available on GitHub. Then open\nPowerShell and run the following commands.\n\n**WARNING: these instructions are currently incomplete.**\n\nCreate a dev directory if you do not have one already::\n\n    \u003e cd ~\n    \u003e mkdir Development\n    \u003e cd Development\n\nClone the DativeTop source code, check out the current dev branch, and clone the submodules::\n\n    \u003e git clone https://github.com/dativebase/dativetop.git\n    \u003e cd dativetop\n    \u003e git submodule update --init --recursive\n\nMake note of the location of Python and Pip. In my case, given the default\ninstall using the Python .exe installer, they were at::\n\n    \u003e C:\\Users\\username\\AppData\\Local\\Programs\\Python\\Python36\\python.exe\n    \u003e C:\\Users\\username\\AppData\\Local\\Programs\\Python\\Python36\\Scripts\\pip.exe\n\nCreate the virtual environment using ``venv``::\n\n    \u003e C:\\Users\\username\\AppData\\Local\\Programs\\Python\\Python36\\python.exe -m venv C:\\Users\\username\\Development\\venv\n\nActivate the venv::\n\n    \u003e cd ~\\Development\n    \u003e .\\venv\\Scripts\\Activate.ps1\n\nExtract the pre-built Dative and move it to ``src/dative/dist/``::\n\n    \u003e cd dativetop\\src\\dative\\releases\n    \u003e tar -zxvf release-315b7d9a8e2106612639caf13189eb2de8586278.tar.gz\n    \u003e mv dist ..\\dist\n    \u003e cd ~\\Development\\dativetop\n\nInstall DativeTop's Python dependencies::\n\n    \u003e pip3 install -r requirements.txt\n    \u003e pip3 install -r src/old/requirements/testsqlite.txt\n\t\t\u003e pip3 install -e src/old/\n\t\t\u003e pip3 install -e src/dativetop/server/\n\nTODO: continue these instructions.\n\n\nBuild a Release\n================================================================================\n\nUsing Briefcase_, it should be possible to build a production release of\nDativeTop locally. Building DativeTop means constructing native application\npackages for a particular target platform, e.g., Mac OS X or Windows.\n\nThe catch is that you must be on the platform for which you are building. That\nis, you can only build a MacOS release on a Mac and a Windows release on Windows.\n\n\nBuild on Mac OS\n--------------------------------------------------------------------------------\n\nTo build a production release of DativeTop on MacOS run::\n\n    $ make build-macos\n\nThe core of the above command is a call to ``briefcase build``. The make command\ndoes a little more work by pruning out some unnecessary files and directories\nthat are not needed in the DativeTop app.\n\nIf successful, your ``.app`` application directory will be at\n``macOS/DativeTop/DativeTop.app``. Mac treats these directories as applications.\nYou should be able to double-click this file in order to run DativeTop.\n\nOnce the build has been created under ``macOS/``, you may build a release (.dmg)\nfile with::\n\n    $ briefcase package --no-sign\n\nIf successful, the above will create the versioned .dmg file under the\n``macOS/`` directory. You can double-click this file and Finder will display a\nvolume containing DativeTop where you can drag DativeTop to you Applications\nfolder to install it, just like any other app.\n\nTo clear out all existing OLDs and DativeTop state, use the following\nconvenience make command::\n\n    $ make refresh-dativetop\n\nThe above is useful if you are building DativeTop repeatedly during a debugging,\ntesting, and/or development scenario.\n\n\nBuild on Windows\n--------------------------------------------------------------------------------\n\nTODO.\n\n\nTroubleshooting\n================================================================================\n\nLogs\n--------------------------------------------------------------------------------\n\nThe logs for DativeTop running in dev mode can be found at::\n\n    src/dativetop.log\n\nThe logs of a built DativeTop app can be found (on a Mac) at::\n\n    DativeTop.app/Contents/Resources/app/dativetop.log\n\n\nBlank Screen\n--------------------------------------------------------------------------------\n\nIf you launch DativeTop and see a blank screen, it may be that a previous\nDativeTop was not shut down correctly. Search for the offending process and\nkill it::\n\n    $ ps aux | grep dativetop\n    $ someuser       45469   0.0  0.1  4357248  10392 s014  S    10:58am   0:00.12 python -m dativetop\n    $ kill 45469\n    $ make launch\n\n\nPillow (OLD dep) Won't Install\n--------------------------------------------------------------------------------\n\nIf you run into trouble installing Pillow (an OLD dependency for image\nprocessing), then you might need to install libjpeg and zlib. See:\n\n- https://stackoverflow.com/questions/34631806/fail-during-installation-of-pillow-python-module-in-linux\n- https://github.com/python-pillow/Pillow/issues/3438\n\nOn Mac OS 10.14 (Mojave), I had to install the zlib headers by manually\ninstalling the macOS SDK headers (YMMV)::\n\n    $ brew install libjpeg zlib\n    $ sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target /\n\n\nViewing Console Output from a Build\n--------------------------------------------------------------------------------\n\nSometimes a built DativeTop is failing mysteriously and inspecting the logs is\ninsufficient. If you double-click on ``DativeTop.app`` and the application does\nnot work as expected, you can launch DativeTop manually such that any exceptions\nthat are raised by the underlying Python code are visible in the terminal::\n\n    $ macOS/DativeTop.app/Contents/MacOS/DativeTop\n\n\nDeveloper Conveniences\n================================================================================\n\nTo view the convenience ``make`` commands that are available::\n\n    $ make help\n\nNote that some of these make commands are no longer applicable and should be\ndeprecated.\n\n\nKnown issues\n================================================================================\n\nFile upload does not work on Mac OS X\n--------------------------------------------------------------------------------\n\nWhen you click the \"Choose file\" button in the \"New File\" interface, the file\nbrowse menu does not open up. This is a known issue with Toga related to the\nCocoa WebView widget. See the `DativeTop cannot upload files`_ issue on GitHub.\n\nThe workaround at present is to open DativeTop's local Dative in a browser and\ndo your file upload from there. DativeTop makes this easy: click on the \"Help\"\nmenu and then click \"Visit Dative in Browser\".\n\nNote that this issue is really a non-issue in the context of read-only local\nOLDs since files cannot be uploaded in such OLDs anyway because they are\nread-only. It will become a more significant issue when the read-only\nrestriction is removed at a later iteration.\n\n\nArchitecture\n================================================================================\n\nThis section describes each of the components of DativeTop.\n\n- DativeTop Toga App:\n\n  - minimal Toga native GUI components: WebViews, top-level menu items, icons\n  - starts and serves local servers for 4 other components: Dative GUI, OLD\n    Service, DativeTop Service, DativeTop GUI.\n\n- Dative GUI (a.k.a., Dative App): interface to multiple OLD instances\n- OLD Service: serves OLD instances at local URLs\n- DativeTop GUI: interface to DativeTop Service\n- DativeTop Service: the source of truth on the local OLD instances, the Dative\n  App, the OLD Service, and the queue of sync-OLD! commands.\n- SyncManager: thread that ensures each auto-syncing OLD has a sync-OLD! command\n  when it needs one.\n- SyncWorker: thread that performs the auto-syncing of OLDs.\n\n\nUsing DativeTop\n================================================================================\n\nWhen the DativeTop app is running, it should open a platform-native window\ndisplaying the DativeTop GUI. This is where you view your local OLD instances\nand create new ones.\n\nTo view your local OLDs via the Dative GUI, click View \u003e Dative in DativeTop's\ntop-level menubar, or use the cmd/ctrl-D shortcut. In order to access the\nlocal OLD, you first have to tell Dative that it exists. From within Dative,\nfirst click on Dative \u003e Application Settings, then click on the Servers button,\nand then click the \"+\" (\"create a new server\") button. The \"Name\" of the OLD can\nbe anything but a good choice is same name as that specified in the DativeTop\nGUI when the OLD was created. The \"URL\" of the OLD must be the URL of the local\nOLD server (likely http://127.0.0.1:5679), followed by a forward slash and then\nthe slug of the OLD, e.g., http://127.0.0.1:5679/aa1.\n\nOnce you have created the OLD server within Dative, you will be able to login to\nthe OLD from Dative as usual. Each instance you create will have the same\nusername and password:\n\n- username: ``admin``\n- password: ``adminA_1``\n\nIf you want to auto-sync this OLD with an external OLD, you must enable auto-sync\nand also specify the URL, username and password of its remote parent OLD.\n\n- auto-sync?: Click the auto-sync? checkbox to enable automated\n  synchronization between this local OLD and its remote (parent) OLD.\n- remote OLD URL: Specify the URL of the remote OLD. For example, use\n  https://do.onlinelinguisticdatabase.org/blaold to specify the Blackfoot OLD.\n\n  - During development/testing, this may be a local OLD that is being served by a\n    separate process, e.g., via the `DativeBase docker-compose local deployment\n    strategy`_.\n  - Note that the remote OLD must be running a version that supports the\n    ``/sync`` endpoint.\n\n- remote OLD username/password: Your credentials that allow you to login to the\n  remote OLD.\n\nDativeTop uses DativeTop Server to manage its state in a SQLite database.\nIf you need to debug the operation of Dativetop, it may be helpful to know that\nits database file and its log file can be found at:\n\n- db file: ``src/dativetop/server/dativetop.sqlite``\n- log file: ``src/dativetop.log``\n\nYour local OLD instances are all read-only. This means that Dative will allow\nyou to *try* to update, create and delete entities (e.g., forms), but the\nunderlying OLD instance will prohibit such actions.\n\nEach local OLD instance has its own SQLite database and filesystem directory.\nThe names of both of these will be determined by the \"slug\" of the OLD that you\nhave specified. For example, if the slug is ``aa1``, then the OLD's database\nfile and filesystem directory will be found at:\n\n- OLD db file: ``src/old/aa1.sqlite``\n- OLD directory: ``src/old/store/aa1/``\n\nWhen DativeTop is running, both Dative and the OLD will be served locally.\nThis means that you can access them from a regular web browser (e.g., Chrome,\nFirefox, etc.) at the following URLs:\n\n- Dative: http://127.0.0.1:5678/\n- The *aa1* OLD instance: http://127.0.0.1:5679/aa1/\n\nWhen you are running a DativeTop instance that has been built for Mac OS, all of\nthe paths described above are still valid, except you must replace the ``src``\nwith ``macOS/DativeTop/DativeTop.app/Contents/Resources/app``. For example, the\nDativeTop SQLite database file will be at\n``macOS/DativeTop/DativeTop.app/Contents/Resources/app/dativetop/server/dativetop.sqlite``.\n\n\n.. _`BeeWare`: https://github.com/pybee/beeware\n.. _`Briefcase`: https://github.com/pybee/briefcase\n.. _`Dative`: https://github.com/dativebase/dative\n.. _`DativeBase`: https://github.com/dativebase/dativebase\n.. _`DativeBase docker-compose local deployment strategy`: https://github.com/dativebase/dativebase/tree/master/docker-compose\n.. _`DativeTop cannot upload files`: https://github.com/dativebase/dativebase/issues/16\n.. _`OLD`: https://github.com/dativebase/old-pyramid\n.. _`Toga`: https://github.com/pybee/toga\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdativebase%2Fdativetop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdativebase%2Fdativetop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdativebase%2Fdativetop/lists"}