-
Notifications
You must be signed in to change notification settings - Fork 277
Expand file tree
/
Copy pathjustfile
More file actions
2402 lines (2075 loc) · 87.2 KB
/
justfile
File metadata and controls
2402 lines (2075 loc) · 87.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# Crossbar.io justfile
# See: https://github.com/casey/just
# -----------------------------------------------------------------------------
# -- just global configuration
# -----------------------------------------------------------------------------
set unstable := true
set positional-arguments := true
# project base directory = directory of this justfile
PROJECT_DIR := justfile_directory()
# package version is managed in these files
PY_VERSION_FILE := "src/crossbar/_version.py"
TOML_VERSION_FILE := "pyproject.toml"
# Default recipe: show project info and list all recipes
default:
#!/usr/bin/env bash
set -e
VERSION=$(grep '^version' pyproject.toml | head -1 | sed 's/.*= *"\(.*\)"/\1/')
GIT_REV=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
echo ""
echo "==============================================================================="
echo " Crossbar.io "
echo ""
echo " Multi-protocol (WAMP/WebSocket, REST/HTTP, MQTT) application router "
echo " for microservices and distributed applications "
echo ""
echo " Python Package: crossbar "
echo " Python Package Version: ${VERSION} "
echo " Git Version: ${GIT_REV} "
echo " Protocol Specification: https://wamp-proto.org/ "
echo " Documentation: https://crossbar.io/docs/ "
echo " Package Releases: https://pypi.org/project/crossbar/ "
echo " Source Code: https://github.com/crossbario/crossbar "
echo " Copyright: typedef int GmbH (Germany/EU) "
echo " License: EUPL-1.2 "
echo ""
echo " >>> Created by The WAMP/Autobahn/Crossbar.io OSS Project <<< "
echo "==============================================================================="
echo ""
just --list
echo ""
# Tell uv to use project-local cache directory.
export UV_CACHE_DIR := './.uv-cache'
# Use this common single directory for all uv venvs.
VENV_DIR := './.venvs'
# Define a justfile-local variable for our environments.
ENVS := 'cpy314 cpy313 cpy312 cpy311 pypy311'
# -----------------------------------------------------------------------------
# -- Helper recipes
# -----------------------------------------------------------------------------
# Internal helper to map Python version short name to full uv version spec
_get-spec short_name:
#!/usr/bin/env bash
set -e
case {{short_name}} in
cpy314) echo "cpython-3.14";;
cpy313) echo "cpython-3.13";;
cpy312) echo "cpython-3.12";;
cpy311) echo "cpython-3.11";;
cpy310) echo "cpython-3.10";;
pypy311) echo "pypy-3.11";;
pypy310) echo "pypy-3.10";;
*) echo "Unknown environment: {{short_name}}" >&2; exit 1;;
esac
# Internal helper that calculates and prints the system-matching venv name.
_get-system-venv-name:
#!/usr/bin/env bash
set -e
SYSTEM_VERSION=$(/usr/bin/python3 -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
ENV_NAME="cpy$(echo ${SYSTEM_VERSION} | tr -d '.')"
if ! echo "{{ ENVS }}" | grep -q -w "${ENV_NAME}"; then
echo "Error: System Python (${SYSTEM_VERSION}) maps to '${ENV_NAME}', which is not a supported environment in this project." >&2
exit 1
fi
# The only output of this recipe is the name itself.
echo "${ENV_NAME}"
# Helper recipe to get the python executable path for a venv
_get-venv-python venv="":
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
VENV_NAME=$(just --quiet _get-system-venv-name)
fi
VENV_PATH="{{VENV_DIR}}/${VENV_NAME}"
if [[ "$OS" == "Windows_NT" ]]; then
echo "${VENV_PATH}/Scripts/python.exe"
else
echo "${VENV_PATH}/bin/python3"
fi
# -----------------------------------------------------------------------------
# -- General/global helper recipes
# -----------------------------------------------------------------------------
# Setup bash tab completion for the current user (to activate: `source ~/.config/bash_completion`).
setup-completion:
#!/usr/bin/env bash
set -e
COMPLETION_FILE="${XDG_CONFIG_HOME:-$HOME/.config}/bash_completion"
MARKER="# --- Just completion ---"
echo "==> Setting up bash tab completion for 'just'..."
# Check if we have already configured it.
if [ -f "${COMPLETION_FILE}" ] && grep -q "${MARKER}" "${COMPLETION_FILE}"; then
echo "--> 'just' completion is already configured."
exit 0
fi
echo "--> Configuration not found. Adding it now..."
# 1. Ensure the directory exists.
mkdir -p "$(dirname "${COMPLETION_FILE}")"
# 2. Add our marker comment to the file.
echo "" >> "${COMPLETION_FILE}"
echo "${MARKER}" >> "${COMPLETION_FILE}"
# 3. CRITICAL: Run `just` and append its raw output directly to the file.
# No `echo`, no `eval`, no quoting hell. Just run and redirect.
just --completions bash >> "${COMPLETION_FILE}"
echo "--> Successfully added completion logic to ${COMPLETION_FILE}."
echo ""
echo "==> Setup complete. Please restart your shell or run the following command:"
echo " source \"${COMPLETION_FILE}\""
# Remove ALL generated files, including venvs, caches, and build artifacts. WARNING: This is a destructive operation.
distclean:
#!/usr/bin/env bash
set -e
echo "==> Performing a deep clean (distclean)..."
# 1. Remove top-level directories known to us.
echo "--> Removing venvs, cache, and build/dist directories..."
rm -rf {{UV_CACHE_DIR}} {{VENV_DIR}} build/ dist/ wheelhouse/ .pytest_cache/ .ruff_cache/ .mypy_cache/
rm -rf docs/_build/
rm -f ./*.so
rm -f ./.coverage.*
rm -rf ./_trial_temp
# 2. Use `find` to hunt down and destroy nested artifacts
echo "--> Searching for and removing nested Python caches..."
find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
echo "--> Searching for and removing compiled Python files..."
find . -type f -name "*.pyc" -delete 2>/dev/null || true
find . -type f -name "*.pyo" -delete 2>/dev/null || true
echo "--> Searching for and removing setuptools egg-info directories..."
find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
echo "--> Searching for and removing coverage data..."
rm -f .coverage
find . -type f -name ".coverage.*" -delete 2>/dev/null || true
echo "==> Distclean complete. The project is now pristine."
# Display project version
version:
@python -c "from crossbar._version import __version__; print(__version__)"
# Clean build artifacts and caches
clean:
rm -rf ./build
rm -rf ./dist
rm -rf ./crossbar.egg-info
rm -rf ./.crossbar
rm -rf ./tests
rm -rf ./.tox
rm -rf ./vers
rm -f .coverage.*
rm -f .coverage
rm -rf ./htmlcov
rm -rf ./_trial*
rm -rf ./pip-wheel-metadata
rm -rf ./docs/_build
rm -rf ./.mypy_cache
rm -rf ./.pytest_cache
rm -rf ./.ruff_cache
find . -name "*.db" -exec rm -f {} \; 2>/dev/null || true
find . -name "*.pyc" -exec rm -f {} \; 2>/dev/null || true
find . -name "*.log" -exec rm -f {} \; 2>/dev/null || true
find . \( -name "*__pycache__" -type d \) -prune -exec rm -rf {} + 2>/dev/null || true
-find . -type d -name _trial_temp -exec rm -rf {} \; 2>/dev/null || true
# -----------------------------------------------------------------------------
# -- Python virtual environments
# -----------------------------------------------------------------------------
# List all Python virtual environments
list-all:
#!/usr/bin/env bash
set -e
echo
echo "Available CPython run-times:"
echo "============================"
echo
uv python list --all-platforms cpython
echo
echo "Available PyPy run-times:"
echo "========================="
echo
uv python list --all-platforms pypy
echo
echo "Mapped Python run-time shortname => full version:"
echo "================================================="
echo
for env in {{ENVS}}; do
spec=$(just --quiet _get-spec "$env")
echo " - $env => $spec"
done
echo
echo "Create a Python venv using: just create <shortname>"
# Create a single Python virtual environment (usage: `just create cpy312` or `just create`)
create venv="":
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
# This is the "default parameter" logic.
# If VENV_NAME is empty (because `just create` was run), calculate the default.
if [ -z "${VENV_NAME}" ]; then
echo "==> No venv name specified. Auto-detecting from system Python..."
VENV_NAME=$(just --quiet _get-system-venv-name)
echo "==> Defaulting to venv: '${VENV_NAME}'"
fi
VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
# Only create the venv if it doesn't already exist
if [ ! -d "${VENV_PATH}" ]; then
# Get the Python spec just-in-time
PYTHON_SPEC=$(just --quiet _get-spec "${VENV_NAME}")
echo "==> Creating Python virtual environment '${VENV_NAME}' using ${PYTHON_SPEC} in ${VENV_PATH}..."
mkdir -p "{{ VENV_DIR }}"
uv venv --seed --python "${PYTHON_SPEC}" "${VENV_PATH}"
echo "==> Successfully created venv '${VENV_NAME}'."
else
echo "==> Python virtual environment '${VENV_NAME}' already exists in ${VENV_PATH}."
fi
${VENV_PYTHON} -V
${VENV_PYTHON} -m pip -V
echo "==> Activate Python virtual environment with: source ${VENV_PATH}/bin/activate"
# Meta-recipe to run `create` on all environments
create-all:
#!/usr/bin/env bash
for venv in {{ENVS}}; do
just create ${venv}
done
# Get the version of a single virtual environment's Python (usage: `just version-venv cpy312`)
version-venv venv="":
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
echo "==> No venv name specified. Auto-detecting from system Python..."
VENV_NAME=$(just --quiet _get-system-venv-name)
echo "==> Defaulting to venv: '${VENV_NAME}'"
fi
if [ -d "{{ VENV_DIR }}/${VENV_NAME}" ]; then
echo "==> Python virtual environment '${VENV_NAME}' exists:"
"{{VENV_DIR}}/${VENV_NAME}/bin/python" -V
else
echo "==> Python virtual environment '${VENV_NAME}' does not exist."
fi
echo ""
# Get versions of all Python virtual environments
version-all:
#!/usr/bin/env bash
for venv in {{ENVS}}; do
just version-venv ${venv}
done
# -----------------------------------------------------------------------------
# -- Package version management
# -----------------------------------------------------------------------------
# Display current version from both files
file-version:
@echo "Python file: $(grep '__version__' {{PY_VERSION_FILE}} | cut -d ' ' -f 3)"
@echo "TOML file: $(grep '^version =' {{TOML_VERSION_FILE}} | cut -d ' ' -f 3)"
# Prepare for release: Remove the .devN suffix from package version files
prep-release:
@echo "Cleaning version for stable release..."
sed -i 's/\.dev[0-9]*//' {{PY_VERSION_FILE}}
sed -i 's/\.dev[0-9]*//' {{TOML_VERSION_FILE}}
uv lock
@just version
@echo 'Now:'
@echo ''
@echo ' 1. Git commit: git add . && git commit -m "version bump for stable release"'
@echo ' 2. Git push commit: git push upstream'
@echo ' 3. Git tag: git tag -a v<VERSION> -m "tagged stable release"'
@echo ' 4. Git push tag: git push upstream v<VERSION>'
@echo ' 5. Bump to new dev version: just bump-next <NEXT-VERSION>.dev1'
@echo ' 6. Create a new rel key: signify-openbsd -G -c "Crossbar.io 26.1" -p src/crossbar/common/keys/crossbar-26-1.pub -s crossbar-26-1.sec'
@echo ' 7. Test rel key: crossbar version'
@echo ''
@echo 'For rel key: this must be done (incl. *.sec key handling) by maintainer!'
@echo ''
# Auto-bump to next dev version based on current date (CalVer: YY.M.1.dev1)
bump-dev:
#!/usr/bin/env bash
set -e
NEXT="$(date +%-y).$(date +%-m).1.dev1"
echo "Auto-computed next dev version: ${NEXT}"
just bump-next "${NEXT}"
# Post-Tag Bump: Set a specific next version (e.g. `just bump-next 26.1.2.dev1`)
bump-next next_version:
@echo "Bumping metadata to {{next_version}}..."
# Update Python source
sed -i 's/__version__ = .*/__version__ = "{{next_version}}"/' {{PY_VERSION_FILE}}
# Update pyproject.toml (matches line starting with version =)
sed -i 's/^version = .*/version = "{{next_version}}"/' {{TOML_VERSION_FILE}}
# Sync the lockfile to the new version
uv lock
# Commit the changes
git add {{PY_VERSION_FILE}} {{TOML_VERSION_FILE}} uv.lock
git commit -m "chore: bump version to {{next_version}}"
@echo "Branch is now at {{next_version}} and ready for development."
# Full workflow helper
release:
@just prep-release
@echo ""
@echo "VERSION PREPARED. Run the following to finalize:"
@echo "----------------------------------------------"
@V=$(bash grep -oE "[0-9.]+" {{PY_VERSION_FILE}} | head -1); \
echo "git commit -am \"v$$V\""; \
echo "git tag -a v$$V -m \"v$$V\""; \
echo "git push && git push --tags"
@echo "----------------------------------------------"
@echo "Then run: just bump-next <NEXT_VERSION_DEV>"
# -----------------------------------------------------------------------------
# -- Installation
# -----------------------------------------------------------------------------
# Install this package and its run-time dependencies in a single environment (usage: `just install cpy312` or `just install`)
install venv="": (create venv)
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
echo "==> No venv name specified. Auto-detecting from system Python..."
VENV_NAME=$(just --quiet _get-system-venv-name)
echo "==> Defaulting to venv: '${VENV_NAME}'"
fi
VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
echo "==> Installing package with package runtime dependencies in ${VENV_NAME}..."
${VENV_PYTHON} -m pip install .
# Install this package in development (editable) mode and its run-time dependencies in a single environment (usage: `just install-dev cpy312` or `just install-dev`)
install-dev venv="": (create venv)
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
echo "==> No venv name specified. Auto-detecting from system Python..."
VENV_NAME=$(just --quiet _get-system-venv-name)
echo "==> Defaulting to venv: '${VENV_NAME}'"
fi
VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
echo "==> Installing package - in editable mode - with package runtime dependencies in ${VENV_NAME}..."
${VENV_PYTHON} -m pip install -e .[dev]
# Meta-recipe to run `install` on all environments
install-all:
#!/usr/bin/env bash
set -e
for venv in {{ENVS}}; do
just install ${venv}
done
# Meta-recipe to run `install-dev` on all environments
install-dev-all:
#!/usr/bin/env bash
for venv in {{ENVS}}; do
just install-dev ${venv}
done
# Install with locally editable WAMP packages for cross-repo development (usage: `just install-dev-local cpy312` or `just install-dev-local`)
install-dev-local venv="": (create venv)
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
echo "==> No venv name specified. Auto-detecting from system Python..."
VENV_NAME=$(just --quiet _get-system-venv-name)
echo "==> Defaulting to venv: '${VENV_NAME}'"
fi
VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
echo "==> Installing WAMP packages in editable mode from local repos..."
echo "==> Looking for sibling repos (../txaio, ../autobahn-python, etc.)..."
# Install local WAMP packages in editable mode
# txaio - no extras needed
if [ -d "../txaio" ]; then
echo " ✓ Installing txaio from ../txaio"
${VENV_PYTHON} -m pip install -e "../txaio"
else
echo " ⚠ Warning: ../txaio not found, skipping"
fi
# autobahn-python - install with extras needed by crossbar
if [ -d "../autobahn-python" ]; then
echo " ✓ Installing autobahn-python with extras from ../autobahn-python"
${VENV_PYTHON} -m pip install -e "../autobahn-python[twisted,encryption,compress,serialization,scram]"
else
echo " ⚠ Warning: ../autobahn-python not found, skipping"
fi
# zlmdb, cfxdb, wamp-xbr - no extras needed
for pkg in zlmdb cfxdb wamp-xbr; do
pkg_path="../${pkg}"
if [ -d "${pkg_path}" ]; then
echo " ✓ Installing ${pkg} from ${pkg_path}"
${VENV_PYTHON} -m pip install -e "${pkg_path}"
else
echo " ⚠ Warning: ${pkg_path} not found, skipping"
fi
done
echo "==> Installing crossbar in editable mode with [dev] extras..."
echo "==> Note: pip will use already-installed local WAMP packages and resolve remaining dependencies"
# Use pip's dependency resolver - it will use the already-installed local WAMP packages
# and install missing dependencies
${VENV_PYTHON} -m pip install -e .[dev] --upgrade --upgrade-strategy only-if-needed
# Install minimal build tools for building wheels (usage: `just install-build-tools cpy312`)
install-build-tools venv="": (create venv)
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
echo "==> No venv name specified. Auto-detecting from system Python..."
VENV_NAME=$(just --quiet _get-system-venv-name)
echo "==> Defaulting to venv: '${VENV_NAME}'"
fi
VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
echo "==> Installing minimal build tools in ${VENV_NAME}..."
${VENV_PYTHON} -V
${VENV_PYTHON} -m pip -V
${VENV_PYTHON} -m pip install build twine auditwheel
# Install the development tools for this Package in a single environment (usage: `just install-tools cpy312`)
install-tools venv="": (create venv)
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
echo "==> No venv name specified. Auto-detecting from system Python..."
VENV_NAME=$(just --quiet _get-system-venv-name)
echo "==> Defaulting to venv: '${VENV_NAME}'"
fi
VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
echo "==> Installing package development tools in ${VENV_NAME}..."
${VENV_PYTHON} -V
${VENV_PYTHON} -m pip -V
${VENV_PYTHON} -m pip install -e .[dev]
# Meta-recipe to run `install-tools` on all environments
install-tools-all:
#!/usr/bin/env bash
set -e
for venv in {{ENVS}}; do
just install-tools ${venv}
done
# -----------------------------------------------------------------------------
# -- Linting, Static Typechecking
# -----------------------------------------------------------------------------
# Automatically fix all formatting and code style issues.
fix-format venv="": (install-tools venv)
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
echo "==> No venv name specified. Auto-detecting from system Python..."
VENV_NAME=$(just --quiet _get-system-venv-name)
echo "==> Defaulting to venv: '${VENV_NAME}'"
fi
VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
echo "==> Automatically formatting code with ${VENV_NAME}..."
# 1. Run the FORMATTER first
"${VENV_PATH}/bin/ruff" format crossbar
# 2. Run the LINTER'S FIXER second
"${VENV_PATH}/bin/ruff" check --fix crossbar
echo "--> Formatting complete."
# Alias for fix-format (backward compatibility)
autoformat venv="": (fix-format venv)
# Lint code using Ruff in a single environment
check-format venv="": (install-tools venv)
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
echo "==> No venv name specified. Auto-detecting from system Python..."
VENV_NAME=$(just --quiet _get-system-venv-name)
echo "==> Defaulting to venv: '${VENV_NAME}'"
fi
VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
echo "==> Linting code with ${VENV_NAME}..."
"${VENV_PATH}/bin/ruff" check src/crossbar/
# Run static type checking with ty (Astral's Rust-based type checker)
# FIXME: Many type errors need to be fixed. For now, we ignore most rules
# to get CI passing. Create follow-up issue to address type errors.
check-typing venv="":
#!/usr/bin/env bash
set -e
VENV_PYTHON=$(just --quiet _get-venv-python {{ venv }})
echo "==> Running static type checks with ty..."
echo " Using Python: ${VENV_PYTHON}"
# ty renamed "not-subscriptable" to "non-subscriptable" between versions;
# detect which name this version uses to avoid unknown-rule warnings.
if ty check --ignore non-subscriptable src/crossbar/__init__.py --python "${VENV_PYTHON}" 2>&1 | grep -q 'Unknown rule.*non-subscriptable'; then
SUBSCRIPT_RULE="not-subscriptable"
else
SUBSCRIPT_RULE="non-subscriptable"
fi
ty check \
--python "${VENV_PYTHON}" \
--ignore unresolved-import \
--ignore unresolved-attribute \
--ignore unresolved-reference \
--ignore unresolved-global \
--ignore possibly-missing-attribute \
--ignore possibly-missing-import \
--ignore call-non-callable \
--ignore invalid-assignment \
--ignore invalid-argument-type \
--ignore invalid-return-type \
--ignore invalid-method-override \
--ignore invalid-type-form \
--ignore unsupported-operator \
--ignore too-many-positional-arguments \
--ignore unknown-argument \
--ignore missing-argument \
--ignore "${SUBSCRIPT_RULE}" \
--ignore not-iterable \
--ignore no-matching-overload \
--ignore conflicting-declarations \
--ignore deprecated \
--ignore unsupported-base \
--ignore invalid-await \
--ignore invalid-super-argument \
--ignore invalid-exception-caught \
--exclude 'src/crossbar/worker/test/examples/syntaxerror.py' \
src/crossbar/
# Run security checks with bandit
check-bandit venv="": (install-tools venv)
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
echo "==> No venv name specified. Auto-detecting from system Python..."
VENV_NAME=$(just --quiet _get-system-venv-name)
echo "==> Defaulting to venv: '${VENV_NAME}'"
fi
VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
echo "==> Running security checks with bandit in ${VENV_NAME}..."
"${VENV_PATH}/bin/bandit" -r src/crossbar/ \
--exclude src/crossbar/worker/test/examples/ \
-ll -f txt
echo "✓ Security checks passed (severity: MEDIUM or higher)"
# Run all checks in single environment (usage: `just check cpy312`)
check venv="": (check-format venv) (check-typing venv) (check-bandit venv)
# -----------------------------------------------------------------------------
# -- Unit tests
# -----------------------------------------------------------------------------
# Run the test suite for Twisted using trial (usage: `just test-trial cpy312`)
test-trial venv="": (install-tools venv) (install venv)
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
echo "==> No venv name specified. Auto-detecting from system Python..."
VENV_NAME=$(just --quiet _get-system-venv-name)
echo "==> Defaulting to venv: '${VENV_NAME}'"
fi
VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
echo "==> Running test suite for Twisted using trial in ${VENV_NAME}..."
${VENV_PYTHON} -m twisted.trial crossbar
# Run the test suite for pytest (usage: `just test-pytest cpy312`)
test-pytest venv="": (install-tools venv) (install venv)
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
echo "==> No venv name specified. Auto-detecting from system Python..."
VENV_NAME=$(just --quiet _get-system-venv-name)
echo "==> Defaulting to venv: '${VENV_NAME}'"
fi
VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
echo "==> Running test suite using pytest in ${VENV_NAME}..."
${VENV_PYTHON} -m pytest -sv src/crossbar/
# Run all tests (trial + pytest + functional)
test venv="": (test-trial venv) (test-pytest venv) (test-functional venv)
# Run functional tests
test-functional venv="": (install-tools venv) (install venv)
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
echo "==> No venv name specified. Auto-detecting from system Python..."
VENV_NAME=$(just --quiet _get-system-venv-name)
echo "==> Defaulting to venv: '${VENV_NAME}'"
fi
VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
echo "==> Running functional tests with ${VENV_NAME}..."
${VENV_PYTHON} -m pytest -sv --no-install ./test/functests/cbtests
# Run all tests
test-all venv="": (test venv) (test-functional venv)
# Generate code coverage report (requires: `just install-dev`)
check-coverage venv="": (install-dev venv)
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
echo "==> No venv name specified. Auto-detecting from system Python..."
VENV_NAME=$(just --quiet _get-system-venv-name)
echo "==> Defaulting to venv: '${VENV_NAME}'"
fi
VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
echo "==> Generating coverage report with ${VENV_NAME}..."
${VENV_PYTHON} -m pytest --cov=src/crossbar --cov-report=html --cov-report=term src/crossbar/
echo "--> Coverage report generated in htmlcov/"
# Alias for check-coverage (backward compatibility)
coverage venv="": (check-coverage venv)
# Upgrade dependencies in a single environment (re-installs all deps to latest)
upgrade venv="": (create venv)
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
echo "==> No venv name specified. Auto-detecting from system Python..."
VENV_NAME=$(just --quiet _get-system-venv-name)
echo "==> Defaulting to venv: '${VENV_NAME}'"
fi
VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
echo "==> Upgrading all dependencies in ${VENV_NAME}..."
${VENV_PYTHON} -m pip install --upgrade pip
${VENV_PYTHON} -m pip install --upgrade -e .[dev]
echo "--> Dependencies upgraded"
# Meta-recipe to run `upgrade` on all environments
upgrade-all:
#!/usr/bin/env bash
set -e
for venv in {{ENVS}}; do
echo ""
echo "======================================================================"
echo "Upgrading ${venv}"
echo "======================================================================"
just upgrade ${venv}
done
# -----------------------------------------------------------------------------
# -- Documentation
# -----------------------------------------------------------------------------
# Install documentation dependencies
install-docs venv="": (create venv)
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
echo "==> No venv name specified. Auto-detecting from system Python..."
VENV_NAME=$(just --quiet _get-system-venv-name)
echo "==> Defaulting to venv: '${VENV_NAME}'"
fi
VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
echo "==> Installing documentation tools in ${VENV_NAME}..."
${VENV_PYTHON} -m pip install -e .[docs]
# Build optimized SVGs from docs/_graphics/*.svg using scour and generate favicon
optimize-images venv="": (install-docs venv)
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
VENV_NAME=$(just --quiet _get-system-venv-name)
fi
VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
SOURCEDIR="{{ PROJECT_DIR }}/docs/_graphics"
TARGETDIR="{{ PROJECT_DIR }}/docs/_static/img"
FAVICONDIR="{{ PROJECT_DIR }}/docs/_static"
echo "==> Building optimized SVG images..."
mkdir -p "${TARGETDIR}"
if [ -d "${SOURCEDIR}" ]; then
find "${SOURCEDIR}" -name "*.svg" -type f | while read -r source_file; do
filename=$(basename "${source_file}")
target_file="${TARGETDIR}/${filename}"
echo " Processing: ${filename}"
"${VENV_PATH}/bin/scour" \
--remove-descriptive-elements \
--enable-comment-stripping \
--enable-viewboxing \
--indent=none \
--no-line-breaks \
--shorten-ids \
"${source_file}" "${target_file}"
done
fi
# Generate favicon from logo SVG using ImageMagick
LOGO_SVG="${TARGETDIR}/crossbar_icon.svg"
FAVICON="${FAVICONDIR}/favicon.ico"
if [ -f "${LOGO_SVG}" ]; then
echo "==> Generating favicon from logo..."
if command -v convert &> /dev/null; then
convert -background none -density 256 "${LOGO_SVG}" \
-resize 48x48 -gravity center -extent 48x48 \
-define icon:auto-resize=48,32,16 \
"${FAVICON}"
echo " Created: favicon.ico"
else
echo " Warning: ImageMagick 'convert' not found, skipping favicon generation"
fi
fi
echo "==> Done building images."
# Build the HTML documentation using Sphinx
docs venv="": (optimize-images venv)
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
echo "==> No venv name specified. Auto-detecting from system Python..."
VENV_NAME=$(just --quiet _get-system-venv-name)
echo "==> Defaulting to venv: '${VENV_NAME}'"
fi
VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
if [ ! -d "${VENV_PATH}" ]; then
just install-tools ${VENV_NAME}
fi
VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
echo "==> Building documentation..."
"${VENV_PATH}/bin/sphinx-build" -b html docs/ docs/_build/html
# Check documentation build
docs-check venv="": (install-tools venv)
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
echo "==> No venv name specified. Auto-detecting from system Python..."
VENV_NAME=$(just --quiet _get-system-venv-name)
echo "==> Defaulting to venv: '${VENV_NAME}'"
fi
VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
echo "==> Checking documentation build..."
# -n: nitpicky mode (warn about missing references)
# -T: show full traceback on error
# Note: -W (warnings as errors) removed - too many cross-package reference warnings
"${VENV_PATH}/bin/sphinx-build" -nT -b dummy docs/ docs/_build
# Open the built documentation in the default browser
docs-view venv="": (docs venv)
#!/usr/bin/env bash
set -e
echo "==> Opening documentation in viewer..."
if command -v xdg-open &> /dev/null; then
xdg-open docs/_build/html/index.html
elif command -v open &> /dev/null; then
open docs/_build/html/index.html
else
echo "==> Could not detect browser opener. Please open manually:"
echo " docs/_build/html/index.html"
fi
# Clean the generated documentation
docs-clean:
echo "==> Cleaning documentation build artifacts..."
rm -rf docs/_build
# Run spelling check on documentation
docs-spelling venv="": (install-docs venv)
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
echo "==> No venv name specified. Auto-detecting from system Python..."
VENV_NAME=$(just --quiet _get-system-venv-name)
echo "==> Defaulting to venv: '${VENV_NAME}'"
fi
VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
TMPBUILDDIR="./.build"
mkdir -p "${TMPBUILDDIR}"
echo "==> Running spell check on documentation..."
"${VENV_PATH}/bin/sphinx-build" -b spelling -d "${TMPBUILDDIR}/docs/doctrees" docs "${TMPBUILDDIR}/docs/spelling"
# -----------------------------------------------------------------------------
# -- Building and Publishing
# -----------------------------------------------------------------------------
# Clean build artifacts
clean-build:
#!/usr/bin/env bash
echo "==> Cleaning build artifacts..."
rm -rf build/ dist/ *.egg-info/
find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
echo "==> Build artifacts cleaned."
# Update uv.lock with latest resolved dependencies (Python 3.11 for widest compatibility)
update-uvlock:
#!/usr/bin/env bash
set -e
echo "==> Updating uv.lock for Python 3.11+ (lowest supported version)..."
uv lock --python 3.11
echo ""
echo "==> uv.lock updated successfully!"
echo ""
just analyze-uvlock
# Analyze uv.lock and print dependency statistics
analyze-uvlock:
#!/usr/bin/env bash
set -e
if [ ! -f "uv.lock" ]; then
echo "ERROR: uv.lock not found. Run 'just update-uvlock' first."
exit 1
fi
echo "==============================================================================="
echo " uv.lock Dependency Analysis "
echo "==============================================================================="
echo ""
# Count total packages in lock file
TOTAL=$(grep -c '^name = ' uv.lock 2>/dev/null || echo "0")
echo "Total packages in uv.lock: ${TOTAL}"
echo ""
# Use uv export to count packages for each installation mode
# This gives accurate counts of what would actually be installed
RUNTIME_COUNT=$(uv export --frozen --no-dev --no-hashes 2>/dev/null | grep -c '==' || echo "0")
DEV_COUNT=$(uv export --frozen --extra dev --no-hashes 2>/dev/null | grep -c '==' || echo "0")
DOCS_COUNT=$(uv export --frozen --extra docs --no-hashes 2>/dev/null | grep -c '==' || echo "0")
ALL_COUNT=$(uv export --frozen --all-extras --no-hashes 2>/dev/null | grep -c '==' || echo "0")
echo "Installation modes (using uv sync):"
echo "─────────────────────────────────────────────────────────────────────────────"
echo ""
printf " %-28s %s\n" "uv sync" "Runtime deps only (${RUNTIME_COUNT} packages)"
printf " %-28s %s\n" "uv sync --extra dev" "Runtime + dev tools (${DEV_COUNT} packages)"
printf " %-28s %s\n" "uv sync --extra docs" "Runtime + docs tools (${DOCS_COUNT} packages)"
printf " %-28s %s\n" "uv sync --all-extras" "All packages (${ALL_COUNT} packages)"
echo ""
# Count extra marker entries in lock file
DEV_ENTRIES=$(grep -c "extra == 'dev'" uv.lock 2>/dev/null || echo "0")
DOCS_ENTRIES=$(grep -c "extra == 'docs'" uv.lock 2>/dev/null || echo "0")
echo "Extra markers in uv.lock (dependency graph entries):"
echo "─────────────────────────────────────────────────────────────────────────────"
echo ""
echo " extra == 'dev': ${DEV_ENTRIES} entries"
echo " extra == 'docs': ${DOCS_ENTRIES} entries"
echo ""
echo "Note: Packages with extra markers are only installed when that extra is"
echo " requested. The markers ensure selective installation."
echo ""
echo "Lock file info:"
echo "─────────────────────────────────────────────────────────────────────────────"
echo ""
echo " File: uv.lock"
echo " Size: $(wc -c < uv.lock | xargs) bytes ($(wc -l < uv.lock | xargs) lines)"
echo " Modified: $(stat -c '%Y' uv.lock 2>/dev/null | xargs -I{} date -d @{} '+%Y-%m-%d %H:%M:%S' 2>/dev/null || stat -f '%Sm' uv.lock 2>/dev/null || echo 'unknown')"
echo ""
echo "==============================================================================="
# Build wheel only (usage: `just build cpy312`)
build venv="": (install-build-tools venv)
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
echo "==> No venv name specified. Auto-detecting from system Python..."
VENV_NAME=$(just --quiet _get-system-venv-name)
echo "==> Defaulting to venv: '${VENV_NAME}'"
fi
VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
echo "==> Building wheel package..."
# Set environment variables for build
export LMDB_FORCE_CFFI=1
export SODIUM_INSTALL=bundled
export PYUBJSON_NO_EXTENSION=1
${VENV_PYTHON} -m build --wheel
ls -la dist/
# Build source distribution only (no wheels)
build-sourcedist venv="": (install-build-tools venv)
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
echo "==> No venv name specified. Auto-detecting from system Python..."
VENV_NAME=$(just --quiet _get-system-venv-name)
echo "==> Defaulting to venv: '${VENV_NAME}'"
fi
VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
echo "==> Building source distribution..."
${VENV_PYTHON} -m build --sdist
ls -la dist/
# Build both source distribution and wheel (usage: `just dist cpy312`)
dist venv="": (install-build-tools venv)
#!/usr/bin/env bash
set -e
VENV_NAME="{{ venv }}"
if [ -z "${VENV_NAME}" ]; then
echo "==> No venv name specified. Auto-detecting from system Python..."
VENV_NAME=$(just --quiet _get-system-venv-name)
echo "==> Defaulting to venv: '${VENV_NAME}'"
fi
VENV_PYTHON=$(just --quiet _get-venv-python "${VENV_NAME}")
echo "==> Building distribution packages (wheel + sdist)..."
${VENV_PYTHON} -m build
echo ""
echo "Built packages:"